An Anthropic API overloaded response is HTTP 529 with error.type set to overloaded_error. The official error reference defines it in one line: 529 - overloaded_error: The API is temporarily overloaded. The same page adds that a 529 can occur when the API sees high traffic across all users. That makes it a server-side capacity signal rather than a request, key, or quota problem. The docs describe the condition as temporary but do not give a recovery time; what you control is the retry schedule and its limits. This guide covers how to tell 529 apart from 429, what the response looks like, how to configure SDK retries, when to fall back or queue, and which common diagnoses are wrong. Facts are checked against the official docs on November 15, 2026.
What HTTP 529 overloaded means
529 is the HTTP status. overloaded_error is the error.type in the JSON body. The official error table lists it alongside 400, 401, 429, 500, 504, and other statuses. As a 5xx status (500 to 599, server-side errors), it points at the server side, not at request validation.
The official definition is short:
529 - overloaded_error: The API is temporarily overloaded.
A 529 error can occur when the API experiences high traffic across all users.
The phrase "across all users" matters. It describes a service-wide traffic condition, not a per-organization rate limit. Anthropic does not publish a recovery time for a 529, and the docs do not promise that a fixed number of retries will succeed. Your controls are the retry schedule and the decision to stop retrying.
Streaming adds a wrinkle. The docs note that an SSE (Server-Sent Events) stream can emit an error event after HTTP 200 has already been returned. The streaming page shows overloaded_error in that event and says it would normally correspond to HTTP 529 outside a stream. If you consume streams, check the event loop, not just the HTTP status.
How 529 differs from 429
The two statuses split like this.
| Status | error.type | Meaning | Whose side | retry-after | What to do |
|---|---|---|---|---|---|
| 429 | rate_limit_error | Your organization hit a rate limit, a tier monthly spend cap (the monthly ceiling for your usage tier), or a Claude Code workspace limit | Your organization or workspace | Some 429s carry it; spend-cap 429s do not | Wait for retry-after; review limits and usage |
| 529 | overloaded_error | The API is temporarily overloaded under high traffic across all users | Server | The error reference does not say 529 carries this header | Retry with backoff; fall back or queue if it persists |
| 500 | api_error | An unexpected error inside Anthropic's systems | Server | Not documented | Retry with exponential backoff; contact support with the request_id if it persists |
| 401 | authentication_error | The API key is malformed, revoked, or expired | Client | Not applicable | Replace the key; do not retry |
| 400 | invalid_request_error | The request format or content is invalid; an organization or workspace spend limit you set also returns 400 | Client | Not applicable | Fix the request or the limit; do not retry |
| 504 | timeout_error | The request timed out while processing | Server or request duration | Not documented | Use streaming or batching for long requests |
Both statuses mean "not right now", but they have different owners. A 429 belongs to your organization's rate limit, spend cap, or Claude Code workspace limit. A 529 belongs to the service's overall load. The recovery path follows from that: a 429 with retry-after tells you when to come back; a 529 gives you no such promise.
Spend-cap 429s deserve their own note. The docs say this response has no retry-after header, and retrying fails until access resumes, including the SDK's automatic retries. The docs also state that access pauses until 00:00 UTC on the first day of the next month unless you request a higher limit sooner. On the Messages API, you can identify the response with error.details.error_code set to enforced_spend_limit_reached. When you see that value, stop retrying and deal with the cap.
A second kind of 429 comes from the Claude Code workspace. That limit is checked separately and the response can carry retry-after. If your traffic comes from Claude Code, check the workspace limit first.
There is also a 400 edge case. When usage reaches a spend limit you set on an organization or workspace, the API returns 400 invalid_request_error. For an organization limit, the message starts with You have reached your specified API usage limits; for a workspace limit, it starts with You have reached your specified workspace API usage limits. It is not a 429, and retrying will not restore access.
Both 500 and 529 are 5xx, and the SDKs retry both. The difference is semantic: 500 is an unexpected internal error, while 529 is an explicit overload signal. The caller's response is similar for both: exponential backoff, then fallback if the error persists.
What the response body and headers look like
The docs say errors are always JSON with a top-level error object that includes type and message, plus a request_id field. The generic example:
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "The requested resource could not be found."
},
"request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}
Swap error.type for overloaded_error and you get the 529 shape:
{
"type": "error",
"error": {
"type": "overloaded_error",
"message": "Overloaded"
},
"request_id": "req_..."
}
That version is assembled from the documented error-body format. The message text in a non-streaming response can vary; the Overloaded wording comes from the official streaming event example.
The header to keep is request-id. The docs say every API response includes it, with a value such as req_018EeWyXxfu5pfWkrYcMdjWG, and the same identifier appears as request_id in an error body. Include it when you contact support about a specific request.
retry-after is documented on the rate-limits page. It gives the number of seconds to wait before retrying. The docs also warn that not every 429 carries it, and a spend-cap 429 never does. The error reference does not tie retry-after to 529, so do not assume a 529 response has one.
The anthropic-ratelimit-* headers describe the current rate limit, remaining capacity, and reset time. They are useful for diagnosing 429s, not for identifying a 529.
Streaming has its own path. The docs say an SSE stream can emit an error event after HTTP 200, and that event does not follow the standard HTTP error mechanism. The event looks like this.
event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}
Handle event: error inside the event loop. The docs also note that new event types can be added, so unknown events should be skipped rather than crashing the consumer.
Should you retry?
Look at the status code and error.type first, then decide.
Retry 529, 500, 504, and 429. When a 429 carries retry-after, wait that long. A spend-cap 429 is the exception; it will not clear until access resumes. The official SDKs also retry connection errors, 408 Request Timeout, and 409 Conflict.
Do not retry 400, 401, 402, 403, 404, 413, or 422. They point at the request, the key, billing, permissions, the path, the payload size, or parameter semantics. Sending the same request again will not change the result.
The retry schedule is exponential backoff with jitter. Each failure increases the wait, then multiplies it by a random factor so that many clients do not retry in the same second. The official SDK starts at 0.5 seconds, doubles the delay up to a cap of 8 seconds, and multiplies by a random value between 0.75 and 1.0. If the response has retry-after, the SDK waits for that value instead.
When you write your own loop, cap three things: attempts, the wait per attempt, and the total deadline. One example: five attempts, a delay starting at 1 second and doubling, a 30-second cap per wait, and a 60-second total budget. Those numbers are engineering advice, not an official rule.
Set the retry budget by request type. Interactive calls usually tolerate tens of seconds; batch work can wait minutes. The budget should cover attempts, the wait per attempt, and the total deadline. A cap on attempts alone still allows a long total wait once the backoff reaches its ceiling.
retry-after takes priority over your own backoff. For 429s, the docs say to wait the number of seconds in the header. A 529 response is not guaranteed to include the header, so the code needs to handle both cases.
Do not spin. Retrying immediately after a failure adds load at the worst moment. Do not write an unbounded retry loop either; the client will hang forever.
A retry sends the request again. If the request also triggers a write, a tool call, or another side effect, make the business operation idempotent (running it twice produces the same result) before adding retries.
When the retry budget runs out, log the final error and request_id, then move to fallback or queueing.
Configuring SDK retries
The official error reference says the SDKs automatically retry transient failures, including connection errors, rate limits, and 5xx server errors, with exponential backoff, twice by default, honoring retry-after when present.
The Python SDK also defaults to 2. You can set it per client or per request.
import anthropic
# Client-wide: retry up to 5 times for every request
client = anthropic.Anthropic(max_retries=5)
# Per request: override the retry count for this call only
client.with_options(max_retries=0).messages.create(
model="claude-opus-5-5",
max_tokens=256,
messages=[{"role": "user", "content": "Hello"}],
)
max_retries=0 disables the SDK's built-in retries. If you already have a retry layer, turn the SDK's off so the two do not stack.
The TypeScript SDK uses maxRetries, also defaulting to 2:
const client = new Anthropic({ maxRetries: 5 });
await client.messages.create(
{
model: "claude-opus-5-5",
max_tokens: 256,
messages: [{ role: "user", content: "Hello" }],
},
{ maxRetries: 0 }
);
Which statuses do the SDKs retry? The Python docs list connection errors, 408, 409, 429, and >=500. A 529 is >=500, so it falls inside the default retry policy. In Python, a 529 raises anthropic.OverloadedError, a subclass of InternalServerError. Catch the specific class before the broader one.
The SDK documentation's error table groups all >=500 statuses under InternalServerError; the exact 529 class is defined in the source. The backoff constants are visible there too: default 2 retries, initial wait 0.5 seconds, a per-wait cap of 8 seconds, and a jitter multiplier between 0.75 and 1.0. retry-after takes priority when present. The source also handles retry-after-ms and HTTP-date values, plus the non-standard x-should-retry header. These are implementation details; you do not need to copy all of them, but they explain the behavior you see in logs.
| Item | Python | TypeScript |
|---|---|---|
| Option | max_retries | maxRetries |
| Default | 2 | 2 |
| Client-wide | Anthropic(max_retries=5) | new Anthropic({ maxRetries: 5 }) |
| Per request | client.with_options(max_retries=0) | Second argument: { maxRetries: 0 } |
| 529 exception | anthropic.OverloadedError | InternalServerError (the >=500 class) |
When to fall back, downgrade, or queue
Retry a single 529 first. Consider fallback only after the retry budget is exhausted, or when the product has a hard latency limit.
Interactive calls, such as an IDE waiting for a completion or a chat window waiting for a reply, usually cannot wait long. Set a total latency budget, for example 30 seconds. Past that, switch to a model that is currently available, or tell the user to try again later. Before switching, confirm two things: the model is available now, and its output quality is good enough for the task. Do not downgrade silently; the user should know the result came from a different model.
Batch work, such as overnight evaluations or bulk code changes, fits a queue better. Put the request in a queue, retry later with backoff, and move it to a dead-letter queue (a holding queue for requests that keep failing) after the attempt limit. A queue keeps the request from being lost and stops the client from hammering the service during a 529 spike.
Add a circuit breaker when the failure rate stays high. For example, if the share of 529s in a recent window crosses a threshold, pause calls for a cooldown, then let a small number of requests through. The threshold is a business decision; the docs do not recommend one. The point is to give both the service and your client time to recover.
If a 529 persists for a long time, contact your provider or Anthropic support with the request_id. The docs explicitly say that including this ID helps resolve a specific request faster.
Cost can be a separate reason to switch models. If a fallback also lowers spend, model tiers, context, and caching all change the bill. The internal guide How to Reduce LLM API Cost for Coding Agents walks through that calculation.
Code examples
curl: inspect the status and the error body
curl -sS -D headers.txt -o body.json \
https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 64,
"messages": [{"role": "user", "content": "Say hi in one sentence."}]
}'
head -1 headers.txt
cat body.json
On a 529, the first line of headers.txt shows status 529, and body.json has error.type set to overloaded_error. Keep the request-id from headers.txt together with body.json.
curl --retry does not retry a 529. The official manpage lists its transient (temporary) statuses as 408, 429, 500, 502, 503, 504, 522, and 524; 529 is not among them. To retry in a shell, check the status code yourself:
for i in 1 2 3 4 5; do
code=$(curl -sS -o body.json -w "%{http_code}" \
https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 64,
"messages": [{"role": "user", "content": "Say hi in one sentence."}]
}')
case "$code" in
529|500|504) sleep $(( (1 << i) + RANDOM % 3 )) ;;
*) break ;;
esac
done
This loop is a demonstration: it branches on the status code, increases the wait exponentially, and adds 0 to 2 seconds of jitter. Production code should also read retry-after, enforce a total deadline, and keep request_id after the final failure. curl --retry-all-errors can make curl retry a 529, but the official manpage calls it the "sledgehammer" of retrying: it also retries errors that should not be retried and can resend a request. Do not make it your default.
Python: let the SDK handle retries
The common setup lets the SDK retry and only handles the exception after the budget is spent:
import os
import anthropic
client = anthropic.Anthropic(
api_key=os.environ["ANTHROPIC_API_KEY"],
max_retries=5, # default is 2; raise it to 5 here
)
try:
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=256,
messages=[{"role": "user", "content": "Hello"}],
)
except anthropic.OverloadedError as exc:
# The SDK already retried; this is the final failure.
print("529 overloaded after retries")
print("request_id:", exc.request_id)
print("status_code:", exc.status_code)
raise
anthropic.OverloadedError is the specific exception for a 529. exc.request_id comes from the request-id response header. exc.status_code is 529.
Python: manual backoff
If you need to control the wait, log every attempt, or integrate a company retry framework, disable the SDK's retries:
import os
import random
import time
import anthropic
client = anthropic.Anthropic(
api_key=os.environ["ANTHROPIC_API_KEY"],
max_retries=0, # disable SDK retries to avoid stacking layers
)
MAX_ATTEMPTS = 5
MAX_WAIT = 30.0
def create_message(**kwargs):
for attempt in range(MAX_ATTEMPTS):
try:
return client.messages.create(**kwargs)
except anthropic.OverloadedError as exc:
if attempt == MAX_ATTEMPTS - 1:
print("giving up, request_id:", exc.request_id)
raise
wait = min(2 ** attempt + random.uniform(0, 1), MAX_WAIT)
print(f"529 overloaded, retry {attempt + 1}/{MAX_ATTEMPTS - 1} in {wait:.1f}s")
time.sleep(wait)
except anthropic.RateLimitError as exc:
if attempt == MAX_ATTEMPTS - 1:
print("rate limited, request_id:", exc.request_id)
raise
retry_after = exc.response.headers.get("retry-after")
wait = float(retry_after) if retry_after else min(2 ** attempt + random.uniform(0, 1), MAX_WAIT)
print(f"429 rate limited, retry in {wait:.1f}s")
time.sleep(wait)
message = create_message(
model="claude-opus-5-5",
max_tokens=256,
messages=[{"role": "user", "content": "Hello"}],
)
The loop catches 529 and 429 separately, waits 1, 2, 4, and 8 seconds with added jitter, caps a single wait at 30 seconds, honors retry-after for a 429 when present, and keeps the request_id before raising the final failure. The retry-after handling here assumes seconds. If the server returns an HTTP date, parse it yourself; the SDK handles that format internally.
The example does not handle 500, 504, or connection errors. Production code can add them to the same retry branch or treat them separately according to business priority.
Monitoring and alerting
For a 529 investigation, the logs should answer a few questions: which endpoint was called, which model was used, which attempt failed, how long the client waited, and what the final request_id was. These fields cover it.
| Field | Use |
|---|---|
status_code | Separate 529, 429, and other statuses |
error.type | Separate overloaded_error from rate_limit_error |
request_id | Match the request-id response header; include it in support requests |
model | Check whether failures cluster on one model |
attempt | Show which attempt failed |
wait_seconds | Record how long the client waited |
endpoint | Show which endpoint received the request |
Chart the rates separately. Keep one line for 529s, one for 429s, and one for other 5xx responses. Mixing them hides the difference between a service-wide overload and your own limit.
Two signals are worth alerting on. One is a sustained run of 529s; the other is a rise in retry exhaustion. A single 529 should not page anyone; the SDK's automatic retry handles transient failures first. Set the thresholds for your own traffic. One example is a 529 share above 10 percent over five minutes with more than 50 requests. Those numbers are examples, not official guidance.
When the error rate rises, read error.type first. A majority of overloaded_error points at service load. A majority of rate_limit_error sends you to the rate limits and spend caps. A majority of invalid_request_error sends you to request construction.
Keep request_id searchable in logs. When a user reports a failure, ask for that ID and find the matching request. The docs say including it helps support resolve a specific request faster.
When the SDK handles retries, the application sees the exception left after the retries are spent. Log that final exception, the attempt count, and the request_id; otherwise the log only says the call failed, without showing where it failed.
Common misdiagnoses
| Misdiagnosis | What is actually happening |
|---|---|
| 529 means the key is invalid | 401 authentication_error is the key problem; 529 is unrelated to the key |
| 529 means rate limiting | 429 rate_limit_error is the rate limit or quota problem; 529 is a service overload |
| 529 is a network problem | Network failures usually surface as connection errors or timeouts with no HTTP status; a 529 is an HTTP response from the server |
| 529 means the request is malformed | 400 invalid_request_error is the request problem; the same request can succeed on retry |
| 529 is the same as 500 | Both are 5xx; 500 is an unexpected internal error, while 529 explicitly means overload |
| 529 means the balance is low | 402 billing_error is the billing or payment problem |
| 529 means missing permission | 403 permission_error is the permission problem |
| Switch models or providers on the first 529 | Retry with backoff first; fall back only after the retry budget is spent |
curl --retry will retry a 529 | The official transient list does not include 529; check the status code yourself |
FAQ
How long does an Anthropic API overloaded response last?
The docs only say temporarily overloaded; they do not give a duration. Do not assume it clears in seconds, and do not retry forever. Set a total deadline, then fall back or tell the user to try again later.
Is a 529 a rate limit on your account?
Check error.type. rate_limit_error is a 429 and points at an organization rate limit or spend cap. overloaded_error is a 529 and points at service load. The fields and the handling differ.
How many times do the official SDKs retry?
Both Python and TypeScript retry twice by default. Python uses max_retries, TypeScript uses maxRetries, and both can be set per client or per request.
What should a streaming client do with a 529?
An SSE stream can deliver event: error after HTTP 200, and the error.type can be overloaded_error. Handle that event in the stream loop instead of checking only the HTTP status. Whether to restart the request after a broken stream is a business decision.
How many retries should you use?
The docs do not prescribe a number. The SDKs default to 2. A manual loop often uses 4 or 5 attempts with caps on the wait and the total deadline. Interactive traffic usually has a tighter latency budget than batch work.
Does changing the API key help?
A 529 is a service overload, so a different key does not change how busy the service is. A key problem is a 401.
Bottom line
When an Anthropic API call returns 529, check that error.type is overloaded_error, then retry with exponential backoff and jitter. Honor retry-after when it exists, and fall back to your own wait when it does not. Once the retry budget is spent, switch models, queue the work, or open the circuit. Keep request_id in the logs so a persistent failure can be traced.
Sources
- Anthropic API errors: https://docs.claude.com/en/api/errors
- Anthropic rate limits: https://docs.claude.com/en/api/rate-limits
- Anthropic API versions: https://docs.claude.com/en/api/versioning
- Anthropic streaming docs: https://docs.claude.com/en/build-with-claude/streaming#error-events
- Anthropic Python SDK: https://docs.claude.com/en/api/sdks/python
- Anthropic TypeScript SDK: https://docs.claude.com/en/api/sdks/typescript
- Python SDK source, 529 mapping: https://github.com/anthropics/anthropic-sdk-python/blob/5139cf2e7d07aa618a6c30b7e0c712f10ccb5ad9/src/anthropic/_exceptions.py#L253-L254
- Python SDK source, retry and backoff: https://github.com/anthropics/anthropic-sdk-python/blob/5139cf2e7d07aa618a6c30b7e0c712f10ccb5ad9/src/anthropic/_base_client.py#L874-L968
- Python SDK source, defaults: https://github.com/anthropics/anthropic-sdk-python/blob/5139cf2e7d07aa618a6c30b7e0c712f10ccb5ad9/src/anthropic/_constants.py#L11-L15
- curl manpage: https://curl.se/docs/manpage.html#--retry
Facts are based on the official documentation as fetched on November 15, 2026. Error codes and SDK defaults can change; check the official pages before relying on a specific value.