Errors

HTTP status codes, error codes, and how to retry safely.

Updated May 18, 2026·4 min read

Error response shape

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "Field 'price' must be a positive number.",
    "field": "price",
    "requestId": "req_01H9K3V5..."
  }
}

Common codes

Field	Type	Description
400 invalid_request	client	Body or query is malformed. Inspect `field`.
401 invalid_key	auth	Bearer token missing, expired, or revoked.
403 insufficient_scope	auth	Token lacks the required scope.
404 not_found	client	Object does not exist or your scope hides it.
409 conflict	client	Idempotency-key reuse with different body, or version mismatch.
422 unprocessable	client	Body is valid JSON but violates business rules.
429 rate_limited	client	Slow down. See Retry-After header.
500 internal	server	Our problem. Retry with backoff. Include requestId when contacting support.

Retry policy

Retry idempotent (GET) and explicitly-keyed (POST/PATCH with Idempotency-Key) requests on 5xx and 429. Use exponential backoff: 1s, 2s, 4s, 8s, capped at 30s.

Do not retry 4xx

4xx errors mean the request itself is wrong. Retrying will fail identically. The exception is 429 — retry after the indicated delay.