Core concepts

Errors & status codes

Errors are always valid JSON. There are two error families - request/auth codes in the envelope, and HTTP status codes - plus one legacy quirk to know about.

Two error families

Envelope codes - numeric codes in error.code: request validation in the 400xx range (for example 40001 missing action, 40005 invalid JSON body) and authentication in the 52xx range.
HTTP status codes - 200, 400, 401, 403, 404, 412, 429, 500, 503.

The 200-with-error quirk

Watch out

Some legacy endpoints return HTTP 200 even on failure, with success: false in the body. Always check success === true - never trust the status code alone.

Error object

{
  "success": false,
  "request_id": "…",
  "error": {
    "code": 40005,
    "message": "Invalid JSON body",
    "meta": {}
  }
}

Common codes

Code	Meaning
`40001`	Missing required parameter
`40005`	Invalid JSON body
`5202`-`5209`	Authentication (see Authentication)
`429`	Rate limited - honor `Retry-After` (see Rate limiting)

The full list lives in the error code index.

Getting help

Every error carries a request_id. Capture it and include it in any support request - it lets us find the exact call.