Developer Docs

Errors

The error envelope and what each status code means for a caller.

Every error returns the same JSON envelope — a stable code, a human message, a requestId to quote in support, and a retryable flag. There is no special case.

Error shape

application/json

{
  "code": "insufficient_scope",
  "message": "Human-readable explanation.",
  "requestId": "b1a2… — quote this if you contact support",
  "retryable": false
}

This is the shape for every failure — an application error, a request that fails schema validation (400 validation_error), an unmatched route (404 not_found), and an unexpected server fault (500 internal_error). Branch on the HTTP status first, then on code.

Status codes

Status	Code	Meaning	Retry?
400	`validation_error`	Request validation failed — a missing or invalid parameter or body. (A malformed JSON body returns bad_request.)	No — fix the request.
401	`unauthorized`	The API key is missing, malformed or revoked.	No — check the Authorization header.
402	`credit_cap_exceeded`	The workspace is out of credits for this billing period.	No — top up credits; retrying will not help.
403	`insufficient_scope`	The key is valid but lacks the scope this route requires, or the route is control-plane and not callable with an API key at all.	No — grant the scope or use a session.
404	`not_found`	The resource or route does not exist (some routes return a specific code, e.g. live_session_not_found). An unknown account with on-demand resolve disabled is also a 404.	No.
429	`rate_limit_exceeded`	The key's per-second request limit was exceeded. See the X-RateLimit-* headers.	Yes — back off (respect Retry-After) and retry.
500	`internal_error`	An unexpected server fault. Quote the requestId if it persists.	Yes — retry with backoff.
503	`*_unavailable`	A dependency or dark-shipped feature is unavailable — a feature-specific code such as metering_unavailable or realtime_not_configured.	Yes — retry with backoff.

Retrying

Retry 429 and 5xx with exponential backoff (respect Retry-After when present). Never blind-retry a 4xx other than 429 — the request itself is the problem. The SDKs surface this as error.retryable, and distinguish 402 (out of credits) from 403 (missing scope) so you react correctly.