Error codes

All error responses use a consistent JSON envelope. Use the error field to identify the problem programmatically.

{
  "status": "error",
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Retry after 42 seconds.",
  "details": {}
}

Error code	Status	Meaning	Resolution
`auth_required`	401	Missing or malformed API key	Provide a key via Authorization: Bearer sk_live_... or X-API-Key header.
`key_revoked`	401	API key has been revoked	Generate a new key from the Organization → API Keys page.
`key_expired`	401	API key is past its expiry date	Generate a new key. Set a longer expiry or "Never expires" when creating keys.
`insufficient_scope`	403	Key lacks a required scope for this endpoint	Generate a new key with the required scope (query, tools, conversations, files).
`workspace_access_denied`	403	Key is not scoped to the requested workspace	Either use a different key or generate one with access to this workspace.
`rate_limit_exceeded`	429	Too many requests from this API key	Check the Retry-After response header for how many seconds to wait.
`quota_exceeded`	402	Organization compute quota exhausted	Upgrade your plan from the Billing page, or wait for quota to reset.
`validation_error`	400	Missing or invalid request parameters	Check the errors array in the response body for field-level details.
`workspace_required`	400	workspace_id parameter is required for this endpoint	Pass workspace_id as a query parameter or in the request body.
`agent_error`	500	The agent encountered an error while processing your request	Transient — retry with exponential backoff. Persistent errors indicate a bug.
`not_found`	404	The requested resource does not exist	Check the ID and workspace_id are correct.
`internal_error`	500	An unexpected server-side error occurred	Retry after a short delay. If the problem persists, contact support.

Retry guidance

Safe to retry

429 — after the Retry-After delay
500, 502, 503, 504 — with exponential backoff
Network timeouts

Do not retry

400 — fix the request before retrying
401 — fix the API key
403 — key lacks scope or workspace access
402 — upgrade plan first

SDK exception classes

Python	TypeScript	When raised
AuthenticationError	AuthenticationError	401 responses
PermissionDeniedError	PermissionDeniedError	403 responses
RateLimitError	RateLimitError	429 responses (includes `retry_after` / `retryAfter`)
APIError	APIError	All other non-2xx responses