Claude API errors: what each code means and how to fix it
Updated 2026-11-19
Model page: Claude Sonnet 5.5 API — pricing, specs and the playground
Every Claude API error comes back as JSON with an error object that has a type and a message, plus a request id. The type tells you more than the status code: the same 500 can carry an api_error or a timeout_error, and a 429 can mean a per-minute limit, a sudden-spike limit or a monthly spend cap. Anthropic also warns that new type values can appear, so code should handle unknown types gracefully.
This page is the map. The four errors people search for most each have their own page with the full fix: 529 overloaded, 500, the Claude Code stream idle timeout, and rate limit reached. Facts below are taken from Anthropic's API error reference and the Claude Code error reference, checked on 19 November 2026.
Every Claude API error code at a glance
| Status | error.type | What it means | Retry? |
|---|---|---|---|
| 400 | invalid_request_error | The format or content of the request is wrong. Also returned when you reach a spend limit you set yourself. | No, fix the request |
| 401 | authentication_error | The API key is malformed, revoked or expired. | No, fix the key |
| 402 | billing_error | A problem with billing or payment details. | No |
| 403 | permission_error | The key is not allowed to use this resource. | No |
| 404 | not_found_error | Wrong endpoint path or resource id. | No |
| 409 | conflict_error | The request conflicts with the current state of a resource. | After resolving it |
| 413 | request_too_large | The request is over the byte limit (128 MB for the Messages API). | No, send less |
| 429 | rate_limit_error | A rate limit, a sudden-spike (ramp) limit, or a monthly spend cap. | Yes, after retry-after; never for a spend cap |
| 500 | api_error | An unexpected error inside Anthropic. | Yes, with backoff |
| 504 | timeout_error | The request timed out while processing. Use streaming for long requests. | Yes, preferably streamed |
| 529 | overloaded_error | The API is temporarily overloaded, for all users. | Yes, with backoff |
The messages you see in Claude Code
Claude Code retries temporary failures up to 10 times with exponential backoff before it shows you anything, so by the time you see an error the retries are already spent. It will not repeat a request that failed after a finished text block or tool call, because that could run the same tool twice.
API Error: Repeated 529 Overloaded errors: Anthropic is overloaded. It is not your usage limit and does not count against your quota. Wait, or switch model with /model, since capacity is tracked per model. See the 529 page below.
API Error: 500 Internal server error: a server-side failure, not caused by your prompt or account. Check status.claude.com, wait a minute and send again.
API Error: Request rejected (429) (older versions said "Rate limit reached"): the rate limit on your API key or cloud project. Run /status; a stray ANTHROPIC_API_KEY can route you through a low-tier key instead of your subscription.
Stream idle timeout / The response stopped arriving: the connection stayed open but stopped delivering data, so Claude Code's watchdog cut it.
API Error: 400 due to tool use concurrency issues: the tool_use, tool_result and thinking blocks in the history no longer line up. Run claude update, then /rewind or press Esc twice.
Please run /login · API Error: 401: the credential was rejected. Run /status; an active ANTHROPIC_API_KEY takes precedence over your login, and behind a gateway set with ANTHROPIC_BASE_URL the text after 401 comes from that gateway.
Errors that arrive after a 200 (mid-stream)
With streaming, an error can arrive after the API has already answered 200. It shows up as an event named error in the stream, for example an overloaded_error that would have been a 529 without streaming. Your status-code handling never sees it, so handle error events in the stream as well.
To recover, keep the partial text you already received and send a follow-up request that asks the model to continue where it stopped. Anthropic notes that tool use and thinking blocks cannot be partially recovered, so a turn that broke inside a tool call has to be redone.
A retry policy that works for most apps
Let the SDK retry first: the official Python and TypeScript SDKs retry connection errors, 408, 409, 429 and 5xx twice by default with exponential backoff and honour retry-after. Raise max_retries (maxRetries in TypeScript) for batch work.
Do not retry 400, 401, 403, 404 or 413: the same request will fail the same way.
Treat a 429 without retry-after carefully: a tier spend cap has no retry-after and keeps failing until next month, so retrying only burns time.
Stream long requests: Anthropic recommends streaming or batches for anything that may run over 10 minutes; some networks drop idle connections before that.
Log the request id: every response has a request-id header. Support needs it.
What changes when you call Claude through APIMODELS
On APIMODELS, every current Claude model (Fable 5.2, Opus 5.5, Sonnet 5.5, Haiku 5.5) is served through at least two upstream routes. If the first route returns a 429, a 5xx or fails to connect before the response starts, the request is sent to the next route automatically, and you only see the error when every route has failed. Failed requests are not charged. One limit we cannot get around: once a response has started streaming to you, a failure in the middle of it cannot be moved to another route, so it reaches you as a stream error event.
For long streaming answers, if the upstream has not started responding within 30 seconds we open the stream ourselves with HTTP 200 and send an Anthropic ping event every 15 seconds until the content arrives, and keep sending pings whenever the stream goes quiet. That keeps proxies and client idle timers from cutting a long thinking phase. The trade-off: once that 200 has gone out, a later failure arrives as an error event in the stream rather than as an HTTP status. Our own billing error is 402 insufficient_credits; see the related page below.
Quick start
cURL
curl https://api.apimodels.app/v1/messages \
-H "x-api-key: $APIMODELS_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"stream": true,
"messages": [{"role": "user", "content": "Summarise this error log in three bullet points."}]
}'Python
import anthropic
# Same Anthropic SDK, pointed at APIMODELS. The SDK already retries 408/409/429/5xx
# with exponential backoff (twice by default); raise it for batch jobs.
client = anthropic.Anthropic(
base_url="https://api.apimodels.app",
api_key="sk_...your_apimodels_key...",
max_retries=4,
timeout=600,
)
try:
with client.messages.stream(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Summarise this error log in three bullet points."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
except anthropic.APIStatusError as e:
# e.status_code: 429 / 500 / 529 ...; the body carries error.type and a request id
print("failed:", e.status_code, e.response.headers.get("request-id"), e.message)FAQ
How do I fix an API error in Claude Code?
Read the code after "API Error". 529 and 500 are on Anthropic's side: wait a minute or switch model with /model. 429 means a rate or spend limit: run /status and check for a stray ANTHROPIC_API_KEY. 400 tool-use errors need claude update and then /rewind. 401 means the credential was rejected: run /status and /login.
Which Claude API errors should I retry?
Retry 429 (after the retry-after header), 500, 504 and 529 with exponential backoff; the official SDKs already do this twice by default. Do not retry 400, 401, 403, 404 or 413, because the same request will fail again. A 429 caused by a monthly spend cap has no retry-after and will not clear until the cap resets.
What does "overloaded" mean on Claude?
It is HTTP 529 overloaded_error: Anthropic's API is temporarily overloaded because of high traffic across all users. It is not your rate limit and, in Claude Code, does not count against your quota. Wait and retry with backoff, or switch to another Claude model, since capacity is tracked per model.
Why do I get an error after the response already started?
With streaming, the API can send an error event after answering 200, for example an overloaded_error mid-response. Handle error events in the stream, keep the partial text, and send a follow-up asking the model to continue. Tool calls and thinking blocks cannot be partially recovered and need a fresh turn.
Do failed requests cost money on APIMODELS?
No. A request that fails is not charged on APIMODELS. Current Claude models also run on at least two upstream routes, so an error from the first route before the response starts is retried on the next one automatically, and you only see it when every route has failed.
