Errors

Every error response uses the same shape:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again in 12s.",
    "request_id": "req_01HXYZ..."
  }
}

Always log request_id — support can resolve issues an order of magnitude faster when you include it.

Status codes

Status	Meaning
400	Malformed request — missing or invalid parameter
401	Missing, invalid, or revoked API key
403	Authenticated, but the key lacks the required scope
404	Resource does not exist or is not visible to this workspace
409	State conflict — the resource changed under you
422	Validation failed on a syntactically valid request
429	Rate-limited — see Retry-After header
5xx	Server-side. Safe to retry with backoff.

Error codes

Code	When
invalid_request	The body or query string failed parsing
invalid_api_key	Key not recognized
insufficient_scope	Key authenticated but missing the needed scope
not_found	Resource ID does not exist
rate_limited	Quota exhausted for this minute or day
internal_error	Server-side fault — opens an internal incident

Retry policy

Retry 429 and 5xx with exponential backoff and full jitter. Cap retries at 5 attempts. Do not retry 4xx other than 429 — the request will fail again.