Errors

All errors come back as JSON with a consistent envelope. The HTTP status code tells you the category; the error field tells you the specific reason.

Error envelope

json

{
  "error": "string",
  "error_description": "string (optional)"
}

Status codes

Code	Label	Meaning
200	OK	Request succeeded.
201	Created	Resource created.
400	invalid_request	Body or query is missing or malformed.
401	unauthorized	Missing or invalid Authorization header. Common messages: 'Authorization token required', 'Invalid or expired token', 'Invalid audience', 'Invalid or revoked API key'.
403	forbidden	You authenticated successfully but the resource is gated. Pro-only endpoints return 'Pro subscription required' when the user is on the free tier.
404	not_found	Resource does not exist, or belongs to an organization you are not a member of.
500	server_error	Something went wrong on our end. Safe to retry with backoff.

Example: expired token

json

{
  "error": "Invalid or expired token"
}

Retries

5xx responses are safe to retry with exponential backoff. 4xx responses indicate a client problem and should not be retried until you fix the request. Read-only endpoints are idempotent, so a retry after a network blip will never produce duplicate writes (there are no writes).