Error handling

How errors look and how to handle them defensively.

Error handling

The API uses HTTP status codes plus a structured JSON body. A 4xx response means the request was invalid; a 5xx means we couldn't process it.

Response shape

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests; retry in 30s.",
    "param": null,
    "request_id": "req_01HXY..."
  }
}

Always include the request_id when reaching out to support.

Common codes

Code	Meaning
`unauthorized`	API key missing or invalid.
`forbidden`	Key is valid but lacks permission for this action.
`not_found`	Resource doesn't exist (or you can't see it).
`rate_limited`	You hit the rate limit. Honor the `Retry-After` header.
`validation_error`	Request body failed schema validation; `param` names the field.
`internal`	Something went wrong on our side. Safe to retry with backoff.

Retries

Retry on 5xx and 429 with exponential backoff. Don't retry on 4xx other than 429 — they signal a programmer error and won't fix themselves.

Error handling

How errors look and how to handle them defensively.

Error handling

The API uses HTTP status codes plus a structured JSON body. A 4xx response means the request was invalid; a 5xx means we couldn't process it.

Response shape

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests; retry in 30s.",
    "param": null,
    "request_id": "req_01HXY..."
  }
}

Always include the request_id when reaching out to support.

Common codes

Code	Meaning
`unauthorized`	API key missing or invalid.
`forbidden`	Key is valid but lacks permission for this action.
`not_found`	Resource doesn't exist (or you can't see it).
`rate_limited`	You hit the rate limit. Honor the `Retry-After` header.
`validation_error`	Request body failed schema validation; `param` names the field.
`internal`	Something went wrong on our side. Safe to retry with backoff.

Retries

Retry on 5xx and 429 with exponential backoff. Don't retry on 4xx other than 429 — they signal a programmer error and won't fix themselves.