Errors

How errors are shaped and what to do with them.

Every error comes back in the same shape, so you can handle them consistently:

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key",
    "retryable": false,
    "request_id": "7501d15d-b189-40ea-b8fa-629cf4722618"
  }
}

The fields

code — a stable, machine-readable string. Branch on this, not the message.
message — a human-readable explanation. May change; don’t parse it.
retryable — true means the same request may succeed if you try again (usually after a short wait). false means fix the request first.
request_id — include this when you contact support. It points us straight at your request.

HTTP status codes

Status	Meaning
`400`	Something in your request is invalid.
`401`	Missing or invalid API key.
`402`	Not enough credits.
`403`	Your key isn’t allowed to do this.
`404`	Not found (or not in your workspace).
`429`	Rate limited — slow down.
`5xx`	Something went wrong on our side. Safe to retry if `retryable` is `true`.

Retrying safely

When retryable is true, retry with the same Idempotency-Key so you’re never charged twice. Back off between attempts (e.g. 1s, 2s, 4s).

If a paid request times out and you’re unsure whether it ran, just retry with the same key — you’ll get the original result if it did, or a fresh run if it didn’t.