Predictable failures.

Status codes

Status	Type	Meaning
`400`	`invalid_request_error`	Malformed JSON or bad parameters — fix the request; retrying the same body will fail the same way.
`401`	`authentication_error`	Missing or invalid key. Check the header for the protocol you’re calling.
`403`	`permission_error`	The key is valid but not allowed to do this.
`404`	`not_found`	Unknown route or unknown model id — check the path and the catalog (`GET /v1/models`).
`413`	`invalid_request_error`	Request body too large. Trim the payload or split the work.
`422`	`invalid_request_error`	The request declares a requirement the chosen model cannot guarantee (e.g. a capability the model doesn’t have). Switch models or drop the requirement.
`429`	`rate_limit_error`	Transient rate limit (requests/min, tokens/min or concurrency). Carries `retry-after` (seconds) — back off and retry.
`429`	`allowance_exhausted`	Monthly included usage used up. This is a hard cap: every request — new or cached — returns it until the cycle resets, so retrying won’t help. The message names your plan and the next tier; `retry-after` is the seconds to reset. Upgrade to lift it immediately.
`5xx`	`api_error`	The model did not return a response. Please retry — transient by design; a retry with backoff almost always succeeds.

Error body shape

Every error returns a JSON body with an error object carrying a type and a message. On the Anthropic endpoint it is Anthropic-shaped:

Anthropic-shaped (/v1/messages)

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key."
  }
}

On the OpenAI endpoints it is OpenAI-shaped:

OpenAI-shaped (/v1/chat/completions, /v1/responses, ...)

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid API key."
  }
}

Retries and backoff

The retry recipe every production agent should ship:

Retry only what can succeed — 429 with type rate_limit_error and 5xx. A 429 with type allowance_exhausted won’t clear until the month resets (or you upgrade), and a 4xx will fail identically on every attempt; fix the request instead.
Honor retry-after exactly — on 429 it is the number of seconds until capacity opens. Waiting less just burns attempts.
Exponential backoff with jitter everywhere else — e.g. 1s, 2s, 4s, 8s with ±20% jitter, capped around five attempts.
Fail loud after the cap — surface the final error.message; it is written to be actionable.

Minimal backoff loop

import random, time

def with_retries(send, max_attempts=5):
    for attempt in range(max_attempts):
        r = send()
        if r.status_code < 400:
            return r
        if r.status_code == 429:
            time.sleep(int(r.headers.get("retry-after", "1")))
        elif r.status_code >= 500:
            time.sleep((2 ** attempt) * (1 + random.uniform(-0.2, 0.2)))
        else:
            break  # other 4xx: not retryable
    raise RuntimeError(r.json()["error"]["message"])

The official OpenAI and Anthropic SDKs already do all of this — including honoring retry-after — with no configuration. Hand-rolled HTTP clients are where retries usually go missing.

Streaming failures

If a stream cannot complete, it ends with a protocol-shaped error event rather than silently returning an empty response — your client always learns the turn failed. Treat a mid-stream error like a 5xx: retry the whole request with backoff. See Streaming.

Get started

API reference

Agent-native API

Guides

Reference

Predictable failures.

Status codes

Error body shape

Retries and backoff

Streaming failures

​Status codes

​Error body shape

​Retries and backoff

​Streaming failures

Status codes

Error body shape

Retries and backoff

Streaming failures