Skip to content
Underread.
Guides

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.

By Vemuri Abhiram6 min read
Rack of servers with status lights in a dark room
Rack of servers with status lights in a dark room
On this page

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-after header. The spend-cap response doesn't.
  • The spend-cap response carries error.details.error_code set to enforced_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.

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.