Errors

Every error uses the same envelope.

{
  "error": {
    "code": 402,
    "message": "Insufficient credits",
    "metadata": {"error_type": "insufficient_credits"}
  }
}

code is the HTTP status as a number. Match on it, and on metadata.error_type — never on the message, which is written for a human and may be reworded.

Status codes

• 400 invalid_request — malformed body or a bad parameter.
• 401 invalid_credentials — missing, unknown or revoked key.
• 402 insufficient_credits — balance at or below zero. Every request is refused, including free models: the block is on the account, not the model.
• 403 permission_denied — wrong key class. Usually an inference key on a management endpoint.
• 404 not_found — unknown model or route.
• 413 payload_too_large — longer than the context of every candidate.
• 429 rate_limited — see Limits.
• 451 region_not_served — we do not currently serve your region.
• 502 provider_error — the provider failed. The response carries their status and body.
• 524 provider_unreachable — no provider answered: unreachable, or silent past the deadline. Every candidate was tried.
• 404 no_endpoints_available — no endpoint satisfied the request. Names the filters that emptied the set.
• 503 service_unavailable — a feature this deployment has not configured, such as billing or BYOK key management.
• 529 provider_overloaded — the provider is at capacity.

Which of these are worth retrying

429, 502, 524 and 529 are transient — back off and retry. Failover already tries other providers before you ever see one.

402, 403, 413 and 503 are not. Retrying changes nothing, because the constraint is on your account or your request. 503 in particular is deliberately not a 502: it means every candidate was excluded by a rule you or your organisation set.