Reliability

Errors

Interpret status codes, error envelopes, and temporary versus permanent failures.

View Markdown

OpenAI-compatible endpoints normally return:

{
  "error": {
    "message": "Human-readable explanation",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "metadata": {}
  }
}

Status codes¶

Status	Meaning	Client action
`400`	Invalid JSON, unsupported parameter, endpoint mismatch, or unsupported model capability	Correct the request; do not retry unchanged
`401`	Missing, invalid, expired, inactive, or conflicting credentials	Fix or rotate credentials
`403`	Valid key without model or operation permission	Request access or choose an allowed model
`404`	Unknown model or resource	Refresh the model catalog and correct the ID
`413`	Request body, context, media, or text input too large	Reduce input or output budget
`429`	Key rate/concurrency limit, global/model capacity, queue timeout, vision pool, or media worker saturation	Honor `Retry-After`; retry with jitter
`502`	Upstream transport or protocol failure	Retry cautiously; preserve the request ID
`503`	No currently ready route or a required provider/service is unavailable	Honor `Retry-After`; retry or choose another ready model
`504`	Generation or upstream timeout	Retry with backoff if the operation is safe to repeat

Anthropic Messages uses its own error envelope. It maps relevant upstream 502, 503, and 504 failures to 529 overloaded_error; ordinary rate and concurrency limits remain 429.

Request IDs¶

Generated API responses normally return X-Request-ID and Inference-Id. Record the value with your own sanitized logs. Never log the Authorization header or request/response bodies merely to diagnose an error.