Errors

The API uses conventional HTTP status codes to indicate success or failure. `2xx` means success, `4xx` means the request was rejected (and is usually safe to fix and retry), and `5xx` means something went wrong on our side.

Error format

Errors return a JSON body with an `error` object containing a machine-readable `code`, a human-readable `message`, and an optional `details` map for field-level validation problems.

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "The 'country' parameter must be a 2-letter ISO code.",
    "details": { "country": "Unsupported value 'usa'." }
  },
  "meta": { "request_id": "req_8f2c1a" }
}

Always log request_id

Every response includes `meta.request_id`. Include it when contacting support - it lets us trace the exact request without you sharing your API key.

Status codes

Code	Meaning	Description
200	OK	The request succeeded.
400	Bad Request	A parameter is missing or invalid. Inspect `error.details`.
401	Unauthorized	Missing or invalid API key. See Authentication.
402	Payment Required	Insufficient credits to perform the operation. No work was done.
403	Forbidden	Your plan doesn't include API access, or the resource isn't yours.
404	Not Found	The resource (for example, a job or project id) does not exist.
429	Too Many Requests	Rate limit exceeded. See Rate limiting.
500	Server Error	An unexpected error occurred. Retry with backoff; if it persists, contact support with the `request_id`.