Errors

Every failed request answers with the same body, whichever door you use: the HTTP API, the SDK, the CLI or MCP. Branch on code; fall back to statusCode for coarse categories. Keep the x-request-id header when you report a problem. The sections below start with the envelope, then show what each door does with it.

HTTP

The error envelope

A lookup of a missing record returns:

{
  "success": false,
  "statusCode": 404,
  "message": "Record \"abc123\" not found.",
  "code": "SCHEMA_RECORD_NOT_FOUND"
}

When request-body parsing fails, message is Validation failed, no code is set, and an errors array points at each invalid field. path is an array because it can point into nested fields:

{
  "success": false,
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [{ "path": ["limit"], "message": "Expected number, received string" }]
}

A value that fails its attribute's type or constraints is a different case: it answers SCHEMA_VALIDATION_FAILED, with a code.

Request ids

Every response, success or error, carries an x-request-id header holding a UUID that identifies that exact request on the server side:

x-request-id: 4b2f1c9e-8a3d-4f6b-9c1e-2d7a5e8b0c4f

It is the only response header the API promises. Include it when reporting an issue.

Error codes

The codes you can meet from the SDK, the CLI and MCP:

The HTTP status derives from the code. A code without an explicit mapping answers 500.

Rate limits

The hosted API counts requests per client IP in five buckets, each per minute:

A few routes carry their own limit instead of their bucket's: the relation graph (POST /relations/graph) allows 60 per minute and resolving recent activity (POST /recent-activity/resolve) 30.

Pushing a schema source (PUT /schema/sources/:id) is exempt: a CI run carries a whole schema in one call.

Exceeding a limit returns a 429 in the same envelope, without a code:

{ "success": false, "statusCode": 429, "message": "ThrottlerException: Too Many Requests" }

No rate-limit or retry-after header is promised. x-request-id is the only guaranteed header. Treat a 429 as transient: back off and retry.

Handling errors

Branch on code for precise handling. Fall back to statusCode for categories: 4xx means the request is wrong, so fix it before retrying; 5xx is server-side and safe to retry with backoff. 408 and 429 are safe to retry as-is after backing off. CONFIGURATION_REQUIRED is the one 5xx not worth retrying: the capability is absent from the deployment, and the answer will not change.

SDK

Every failed request throws. The client never returns an error object, never retries, and never swallows a status. Catch by class, read status and code, and decide.

import { StandardsAuthError, StandardsRequestError } from "@standards/client";
import { getStandards } from "./client";
import { incident } from "./schema";

try {
  await getStandards().incidents.get("inc_404");
} catch (error) {
  if (error instanceof StandardsAuthError) throw error; // 401 or 403: fix the key, not the code
  if (error instanceof StandardsRequestError && error.status === 404) return null;
  throw error;
}

The classes

StandardsRequestError carries four fields: status (the HTTP status), message (the server's message, else its error, else its detail, or Request failed with status N when the body has none of them), code (the server's error code, when it sent one, such as SCHEMA_SOURCE_NOT_FOUND) and details (the server's details value, as sent, when there is one). An error body that is not JSON still throws a StandardsRequestError with the fallback message, never a parse error. A 204 answer, or a 200 with an empty body, resolves to null and throws nothing.

The builders throw their own family, at declaration time and without a network: ValidationError for a missing name or label, DuplicateError for a repeated attribute or object name, and SchemaError with a code for a bad object name, a reserved name or a missing labelExpression. All of them extend SchemaError.

standards.files and standards.documents reject with the same ValidationError when a file input is not a Blob, or has no filename or MIME type. They reject before any request is sent.

Order your instanceof checks

Three classes extend StandardsRequestError. An instanceof StandardsRequestError test placed first matches all four, so check the specific classes first:

import {
  SchemaSourceConflictError,
  SchemaSourceValidationError,
  StandardsAuthError,
  StandardsRequestError,
} from "@standards/client";
import { getStandards } from "./client";
import { statusSource } from "./schema";

try {
  await getStandards().schema.sync(statusSource);
} catch (error) {
  if (error instanceof SchemaSourceConflictError) {
    console.error(`"${error.objectName}" is owned by ${error.owner}; rename it`);
  } else if (error instanceof SchemaSourceValidationError) {
    console.error(`the server refused the source: ${error.message}`);
  } else if (error instanceof StandardsAuthError) {
    console.error(`the key lacks architect:update (${error.status})`);
  } else if (error instanceof StandardsRequestError) {
    console.error(`sync failed with ${error.status} ${error.code ?? ""}`);
  } else {
    throw error;
  }
  process.exit(1);
}

Status 0

A refused connection and a timeout both throw StandardsRequestError with status: 0, the message Could not connect to <baseUrl> and no code. The default timeout is 30 seconds per request and covers the wait for the response headers: once they arrive, reading the body is not timed, so a large export finishes however long it takes (race the call against your own deadline if you need a bound on the whole read). set timeoutMs on createStandards to change it for every request, or pass timeoutMs to files.upload or documents.attachToRecord to change it for that one upload. The client makes one attempt. A retry, a backoff or a circuit breaker belongs in your code, where you know whether the call is idempotent.

A 429 is a plain StandardsRequestError with status: 429. The client does not read Retry-After and does not wait.

What the SDK drops

The REST API answers an error with { statusCode, message, code, details, errors[] } and an x-request-id header. The client keeps message, code and details. It drops the errors[] array, so a validation failure on create tells you the first problem in message but not the per-field list, and it drops x-request-id, so a support request has no correlation id from the client side. When you need either, make the call with createTransport and read the response yourself, or reproduce it with the CLI, which prints both.

The three-way degradation

A server that talks to Standards has three distinct failure modes, and a status page should answer each differently. The status page cookbook sorts them with two predicates:

import { StandardsAuthError, StandardsRequestError } from "@standards/client";

/** Connection refused or timeout (status 0), a 5xx, or a key that no longer works. */
export function isStandardsUnreachable(error: unknown): boolean {
  if (error instanceof StandardsAuthError) return true;
  return error instanceof StandardsRequestError && (error.status === 0 || error.status >= 500);
}

/** A 404 on a records route: the workspace answers but has none of our objects. */
export function isSchemaMissing(error: unknown): boolean {
  return (
    error instanceof StandardsRequestError &&
    !(error instanceof StandardsAuthError) &&
    error.status === 404
  );
}

The cron handler turns them into three responses:

try {
  result = await runChecks(deps);
} catch (error) {
  if (error instanceof StandardsAuthError) {
    return json(500, { error: error.code ?? "auth" }); // our configuration is wrong
  }
  if (isStandardsUnreachable(error)) {
    return json(503, { error: "standards_unreachable" }); // try again later
  }
  if (isSchemaMissing(error)) {
    return json(503, { error: "schema_missing" }); // run the sync script
  }
  throw error;
}

An auth failure is a 500 with the server's code: the key is wrong and a retry will not help. An unreachable API is a 503: the next cron run may succeed. A 404 on a records route is also a 503, with a different reason: the workspace answers but the schema source was never synced, so the fix is schema.sync, not waiting. The public page uses the same split to serve the last stored snapshot as stale during an outage, and an empty one when the schema is missing.

CLI

The CLI prints ✗ Error (status): message on stderr and exits with code 1. It exits with exit code 2 when no instance is configured: ✗ Error: No Standards instance configured. Run "standards login" or pass --api-key. Unlike the SDK, the CLI prints the errors[] array and the x-request-id header, so reproduce a failure there when you need either.

MCP

An unknown tool, or a tool your key or scopes withheld, answers a JSON-RPC -32602. Inside a call, the result carries isError: true and a text content Access denied: not authorized to <action> "<object>".

Next steps

• Sync: the two sync errors and what the summary looks like.
• Records: what each verb sends and which status it can answer.
• API keys: why a 403 says nothing and how to grant the missing action.
• CLI: exit codes, output formats and the --instance flag.
• MCP: how an agent sees a withheld tool and a refused call.
• Status page cookbook: the degradation above, wired end to end.
• Book a demo