API reference

Errors

Every error response is a JSON object with a typed code, a human-readable message, and the requestId of the failed call.

Response shape

json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 23s.",
    "requestId": "req_a1b2c3d4e5f6g7h8"
  }
}

The same requestId is also returned in the X-Request-Id response header. Quote it when raising support tickets — it uniquely identifies the request in our logs.

Error codes

Code	HTTP	When it fires
`INVALID_KEY`	401	Missing, malformed, or unknown API key.
`REVOKED_KEY`	401	Key was valid but has been revoked.
`INSUFFICIENT_PLAN`	402	Org is on a plan tier without API access (Free or Starter).
`RATE_LIMITED`	429	Exceeded 100 requests per minute per key.
`NOT_FOUND`	404	Resource does not exist or belongs to a different org.
`BAD_REQUEST`	400	Request was malformed — bad cursor, invalid query param, etc.
`INTERNAL`	500	Unexpected server error. Include the requestId when reporting.

Recommended handling

401 / 402 — surface a clear message to your operator; nothing to do but fix billing or rotate the key.
404 — treat as a permanent miss for that ID. Do not retry.
429 — read the Retry-After header (in seconds), sleep, and retry. See rate limits.
500 — transient. Retry with exponential backoff; if it persists for more than a few minutes, raise a support ticket with the request ID.