Claude API Error 529 “overloaded_error”: What It Means and How to Handle It
529 is Anthropic's capacity, not yours. The dangerous part is the 429 that looks identical and must never be retried.
On this page
- What each code actually means
- 1. Confirm it's really 529 before changing anything
- 2. Check whether your SDK is already retrying
- 3. Back off properly, and cap it
- 4. The spend-cap 429 that breaks naive loops
- 5. Reduce your exposure to overloads
- 6. Measure it, so you know what normal looks like
- Match your symptom to the fix
- When it doesn't clear
A job that's been stable for weeks starts failing in bursts. Not every call — maybe 1 in 10, then half, then most:
anthropic.APIStatusError: Error code: 529 - {'type': 'error',
'error': {'type': 'overloaded_error', 'message': 'Overloaded'}}
Nothing you deployed caused this, and nothing in your account changed. 529 isn't about you at all — it's Anthropic telling every caller at once that there's no capacity right now, which is why it arrives in bursts and clears without you doing anything.
#What each code actually means
| Code | Whose problem | Retry? | Clears by itself? |
|---|---|---|---|
529 overloaded_error |
Anthropic's capacity | Yes, with backoff | Usually within minutes |
429 rate_limit_error |
Your account's limit | Yes, after retry-after |
Yes, on the window |
| 429 spend cap | Your configured ceiling | No | Only when you raise it |
500 api_error |
Their side, unexpected | Once or twice | Sometimes |
#1. Confirm it's really 529 before changing anything
Log the status and the error type together. They're not the same field, and guessing from the message text goes wrong:
from anthropic import Anthropic, APIStatusError
client = Anthropic()
try:
client.messages.create(
model="claude-sonnet-4-5",
max_tokens=256,
messages=[{"role": "user", "content": "ping"}],
)
except APIStatusError as e:
body = getattr(e, "body", {}) or {}
print(e.status_code, body.get("error", {}).get("type"))
If that prints 529 overloaded_error, your code is fine and your account is fine. Skip to section 3.
#2. Check whether your SDK is already retrying
This catches more people than the error itself. The official SDKs retry on their own, and the default is small — around 2 attempts. If you've wrapped the client in your own retry loop, you're multiplying, not adding.
A loop of 6 attempts wrapping an SDK that retries twice is up to 18 requests for 1 logical call. During an overload that's the worst thing you can do: you add load to a service that's already saturated, and you slow your own recovery.
Pick one layer and disable the other:
client = Anthropic(max_retries=0) # you own the retries now
I'd rather own it explicitly than guess what the SDK is doing under me.
#3. Back off properly, and cap it
Exponential backoff with full jitter spreads the retry storm instead of concentrating it:
import random, time
from anthropic import Anthropic, APIStatusError
client = Anthropic(max_retries=0)
def call(**kw):
for attempt in range(5):
try:
return client.messages.create(**kw)
except APIStatusError as e:
body = getattr(e, "body", {}) or {}
etype = body.get("error", {}).get("type")
if e.status_code == 429:
detail = body.get("error", {}).get("details", {}) or {}
if detail.get("error_code") == "enforced_spend_limit_reached":
raise RuntimeError("Spend cap hit — retrying will not help") from e
time.sleep(float(e.response.headers.get("retry-after", 5)))
continue
if e.status_code in (500, 529) or etype == "overloaded_error":
time.sleep(min(60, 2 ** attempt) * random.random())
continue
raise
raise RuntimeError("Still failing after 5 attempts")
Three things in there are deliberate. The cap is 60 seconds, because a 10-minute sleep in a request handler is an outage by another name. The attempts are bounded at 5, because an unbounded retry on a capacity error is how you turn a 3-minute blip into a wedged queue. And the spend-cap check comes first, because it's the one case that looks retryable and isn't.
#4. The spend-cap 429 that breaks naive loops
This is the detail worth taking away. A 429 from an organisation spend limit reports the same error type as an ordinary rate limit. A retry loop keyed only on rate_limit_error will retry it forever.
Two signals separate them:
- A real rate limit sends a
retry-afterheader. The spend-cap response doesn't. - The spend-cap response carries
error.details.error_codeset toenforced_spend_limit_reached.
Branch on that detail, as the example above does, and the loop exits with a clear message instead of hammering a wall. Anthropic's error documentation is the place to confirm the exact field names before you ship it, since response shapes do change.
#5. Reduce your exposure to overloads
You can't stop a 529, but you can stop it taking the whole system down.
Queue instead of blocking. Anything that isn't user-facing belongs on a queue with a dead-letter path, so a 529 turns into a job that runs 4 minutes later instead of a request that failed in front of somebody. This one change converts most capacity incidents from an outage into a graph that looks slightly odd for an hour.
Degrade rather than fail. For an interactive feature, a smaller or older model usually beats an error page, and capacity pressure rarely hits every model equally at the same moment. Decide the fallback order once, in configuration, rather than improvising it during the incident.
Spread the load. Firing 200 parallel calls the instant a cron tick lands maximises your chance of meeting a saturated moment, and it means all 200 fail together rather than a few. A concurrency limit of 10 to 20 with a short queue in front of it usually finishes the whole batch sooner, because you stop spending attempts on requests that were never going to be served.
Add a circuit breaker. After a handful of consecutive 529s, stop calling for 30 seconds and fail fast instead. It sounds counterintuitive to give up early, but during a genuine capacity event your retries are competing with everyone else's, and a brief pause costs you less than a queue full of threads all sleeping on backoff timers.
#6. Measure it, so you know what normal looks like
Count 529s as their own metric rather than folding them into a general error rate. A background level of them is ordinary on a busy API, and if you don't know your baseline you can't tell a real incident from a Tuesday.
Alert on the ratio over a window, not on individual errors. Something like "more than 20% of calls in 5 minutes" catches a genuine capacity event while ignoring the handful your retries already absorbed. Alerting on every 529 trains everyone to ignore the alert, which is worse than having none.
#Match your symptom to the fix
| What you're seeing | Likely cause | Go to |
|---|---|---|
| Bursts of failures, nothing deployed | Genuine 529 overload | 3 |
Retries never succeed, no retry-after |
Spend cap | 4 |
| Far more requests than expected in logs | SDK retries plus your own | 2 |
| Steady 429 that clears on a schedule | Ordinary rate limit | 3 |
| Only your long prompts fail | Token limit, not overload | — |
#When it doesn't clear
A 529 that persists for hours rather than minutes is unusual. Check the status page before debugging further — there's no fix on your side for a regional capacity event.
If the status page is green and you're still getting 529s on every call, capture the request-id response header from several failures and open a support ticket with them. That header is what lets support trace the specific calls. Without it the ticket turns into a conversation about timestamps.
If overload handling is pushing you toward moving scheduled work off the interactive path entirely, the automation shortlist covers the tools that do the queueing for you.
Frequently asked questions
Is 529 a standard HTTP status code?
No. 529 isn't in the HTTP specification — it's a vendor-chosen code. That's worth knowing because some proxies, gateways and client libraries don't handle unknown 5xx codes the way you'd expect.
Does a 529 count against my rate limit or bill?
A failed request returns no tokens, so there's nothing to charge for. The practical risk is the retries around it, not the error itself.
Should I retry 500 the same way as 529?
Retry it once or twice, not 5 times. A 500 can be a transient fault, but it can also be a malformed request that will fail identically every time. 529 is explicitly a capacity signal, so it earns more patience.
Will a higher usage tier stop 529s?
No. Tiers raise your own limits, which is a 429 problem. 529 is capacity shared across all customers, so your tier doesn't change it.
How long should my cap be?
60 seconds total for an interactive path, and whatever your queue tolerates for background work. Beyond a minute a user has already given up, so you're holding a connection for nothing.
Written by
Vemuri Abhiram
Founder & Editor
I write every post here. The tools I review are ones I pay for and run on real client work, not demo accounts, and every number you see came off my own invoice or dashboard.
You might also like
How to Fix “You exceeded your current quota” (insufficient_quota) on the OpenAI API
Two different problems return 429 on the OpenAI API. One is worth retrying and one never is. Here's how to tell them apart in 2 minutes.
Vemuri Abhiram6 min read
How to Fix “Incorrect API key provided” (401 invalid_api_key) on the OpenAI API
A 401 from the OpenAI API usually isn't a bad key. Here are the 6 causes in the order they actually occur, starting with the invisible one.
Vemuri Abhiram6 min read
How to Fix “The model does not exist or you do not have access to it” (model_not_found)
A typo and a permissions problem return the identical model_not_found error. List the models your key can actually reach and the ambiguity disappears.
Vemuri Abhiram6 min read
More from Underread, once a week.
The guides worth reading and the tests worth trusting. One email, every Friday.
No spam. Unsubscribe in one click.