Skip to content
All systems operationalStatus

Error codes

Every error the gateway returns, what it means, and how to fix it.

Error format

Errors use the shape of the protocol you called, so official SDKs raise their usual exception types. The type values are the same on both protocols.

Anthropic-compatible (/v1/messages)
{
  "type": "error",
  "error": {
    "type": "insufficient_balance",
    "message": "Your balance is too low for this request. Add credit to continue."
  }
}
OpenAI-compatible (/v1/chat/completions, /v1/responses)
{
  "error": {
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "message": "Your balance is too low for this request. Add credit to continue."
  }
}

Every response carries an x-request-id header. Include it when you contact support. It lets us find the request without you sharing any content or keys.

Error reference

StatusTypeMeaningWhat to do
400invalid_request_errorThe body is malformed or a parameter is invalid.Check the message for the offending field.
401authentication_errorThe key is missing, malformed, unknown or revoked.Send a valid key; see API keys.
402insufficient_balanceYour balance cannot cover the request.Buy another credit pack in your dashboard; we add the credit to your key.
403permission_errorThe key is disabled, or the model is outside its plan (for example a ChatGPT model on a Claude key).Re-enable the key, pick a model from your plan, or use a Claude & ChatGPT key.
404not_found_errorUnknown model ID or endpoint.Check the model ID and the base URL.
413request_too_largeThe request exceeds the size limit.Send less content or split the work.
429rate_limit_errorToo many requests for this key.Retry after the retry-after header.
500api_errorAn unexpected error on our side.Retry with backoff; contact support if it persists.
503overloaded_errorThe model is temporarily over capacity.Retry with backoff, or try another model.
504timeout_errorThe model did not respond in time.Retry; stream long generations.

Retrying safely

  • Retry 429, 500, 503 and 504 with exponential backoff and jitter. Honor the retry-after header when present.
  • Do not retry other 4xx errors. The same request will fail the same way.
  • The official Anthropic and OpenAI SDKs already retry transient errors twice by default.