Errors

Every failed request answers with the same body. Branch on code; fall back to statusCode for coarse categories. Keep the x-request-id header when you report a problem.

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:

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.

How each door surfaces an error

import { createStandards, StandardsRequestError } from "@stndrds/client";

const standards = createStandards({
  baseUrl: "https://api.standards.new/v1",
  apiKey: process.env.STANDARDS_API_KEY!,
});

try {
  await standards.from("contacts").get("abc123");
} catch (error) {
  if (error instanceof StandardsRequestError && error.status === 0) {
    // Timeout or refused connection: the API was never reached.
  }
  if (error instanceof StandardsRequestError && error.code === "SCHEMA_RECORD_NOT_FOUND") {
    // Branch on the code, not on the message.
  }
  throw error;
}

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.

Next steps

• SDK errors: the error classes, SchemaSourceConflictError, and what a sync reports.
• Workspaces and 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.