overloaded_error
The message
overloaded_errorWhat it means
A 529 overloaded_error means the Claude API is temporarily overloaded, from high traffic across all users rather than anything your organization did. In a streaming response it can arrive after the API has already returned 200.
What to do
Let the official SDKs retry it: exponential backoff, twice by default, honoring retry-after. If you stream, read the error event yourself, then resume from the partial response rather than sending the whole request again.
A 529 from the Claude API comes back with the code overloaded_error, and Anthropic's errors page gives it one line: "The API is temporarily overloaded". The same page says 529 errors can occur when the API experiences high traffic across all users.
- Status
- 529 overloaded_error
- Cause
- high traffic across all users
- SDK behavior
- retries transient failures with exponential backoff, twice by default
- Streaming
- an error can occur after the API returns a 200 response
- Looks like it
- 429 rate_limit_error from acceleration limits after a sharp increase in usage
Why you got it
It says nothing about your account. The errors page files 529 with the server codes rather than the limit codes, and the cause it names is traffic across everybody rather than anything your organization did.
There is one case where your own spike causes trouble, and it arrives under a different code. A sharp increase in usage can trip acceleration limits and come back as 429s, and the docs' fix is to ramp up traffic gradually and maintain consistent usage patterns.
The streaming case
This is where it costs people time. A streamed request returns 200 and then fails partway through, so a client that only reads the HTTP status sees a success and logs nothing.
When receiving a streaming response over server-sent events (SSE), an error can occur after the API returns a 200 response. In that case, error handling doesn't follow these standard mechanisms.
Inside the stream it shows up as an error event whose inner type is overloaded_error and whose message is "Overloaded". Anthropic describes that event as one that "would normally correspond to an HTTP 529 in a non-streaming context", so it's the same problem wearing different clothes.
What to do about it
For an ordinary request, the SDKs have it covered. They retry transient failures, 5xx server errors included, with exponential backoff, twice by default, and they honor the retry-after header when one is there. Each SDK client takes a maximum-retries option (that's how you turn the behavior off, or up).
For a stream, retrying from scratch throws away everything that already arrived. The recovery strategy in the docs is to capture the partial response, construct a continuation request that carries it, and resume from where the stream was interrupted.
Codes that look like it
A 429 rate_limit_error is your own organization's limit or spend cap, and we have a separate page on telling those apart. A 500 api_error is an unexpected error internal to Anthropic's systems, and the docs say to retry with exponential backoff and contact support with the request ID if it keeps happening.
A 504 timeout_error means the request timed out while processing. Granted, that one often has a cause you control: Anthropic's advice for long-running requests, especially those over 10 minutes, is the streaming Messages API or the Message Batches API, because some networks drop idle connections and the request then fails without a response.