Errors and rate limits

Every endpoint fails the same way, so a client handles errors, rate limits and retries once and reuses that code everywhere, including over MCP.

Every non-2xx response is one JSON object:

{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}

• code is the HTTP-level error, for example UNAUTHORIZED, FORBIDDEN, NOT_FOUND, BAD_REQUEST or TOO_MANY_REQUESTS.
• data.reason, when present, is a finer machine-readable reason such as auth.key_not_found or rate_limit.exceeded. Branch on it rather than on message, which is for people and may change.
• defined is true when the operation lists that error in the API reference, and false for errors any request can meet (authentication, rate limits, an unknown route).
• A validation failure answers BAD_REQUEST with the problems in data.formErrors and data.fieldErrors.

Every response also carries an X-Request-ID. Quote it when you contact support, and we can find that exact request.

Every response states the limit it was counted against, in two forms:

• the X-RateLimit-* headers;
• the IETF structured fields RateLimit (live state: r is the requests remaining, t the seconds until the window resets) and RateLimit-Policy (the quota: q is the limit, w the window in seconds).

A 429 also carries Retry-After in seconds and data.retryAfterMs. Wait at least that long before the next request; retrying sooner is counted and refused again.

A write operation that lists an Idempotency-Key header in the API reference can be retried without doing the work twice. Send one key per logical write and repeat the same key on every retry:

• the same key with the same body within 24 hours replays the stored response;
• the same key with a different body is refused with 422;
• a duplicate that arrives while the first is still running gets 409.

An operation without the header is not idempotent, so retry it only when you know the first attempt did not land.