529 overloaded — it arrives by two paths, and only one of them gets retried
- Work out how it arrived: an HTTP 529 was already retried with backoff; an
overloaded_errorinside the stream takes another path that the standard retry mechanisms do not cover — that's the one that dies mid-answer with no retry at all. - 529 is not 429. It's the service saturating for everyone, it doesn't count against your quota, and you hold no lever — concurrency, caching and tier all do nothing.
- Only two things shorten the wait: switch to a comparable model, or let the client keep retrying in unattended runs.
The same 529 shows up two ways: retried ten times before giving up, or cut off mid-answer with no retry at all. That isn't random and it isn't a bug — it's two arrival paths. A 529 returned as an HTTP status code goes through the standard retry channel. A streaming request has already returned 200, so an overload can only arrive as an event inside the stream, and the official docs state plainly that error handling there does not follow the standard mechanisms. Working out which one you have is far more useful than asking how long to wait.
What you're seeing
API Error: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}
API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.
✻ API Error · Retrying in 8s · attempt 3/10
529 Overloaded
model overloadedAnd one more that doesn't look like any of those — which is exactly why it gets misread as a dropped connection:
event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}Two arrival paths: same error, different fate
| HTTP 529 — rejected before it starts | overloaded_error in the stream — partway through | |
|---|---|---|
| HTTP status | 529 | 200 — headers went out long ago |
| Error type | overloaded_error | overloaded_error — identical |
| How it arrives | JSON response body | an event: error in the SSE stream |
| Standard retries? | Yes. Official SDKs retry twice by default; Claude Code up to 10 | No. Official wording: error handling here doesn't follow the standard mechanisms |
| By the time you see it | the retry budget is spent | it may never have been retried at all |
| What it feels like | a long spinner, then an error | text stops mid-word, like the network dropped |
| Output already produced | none | already spent, and the half answer usually can't be kept |
error event explicitly.
529 vs 429: they share the feeling of being turned away, and nothing else
| 529 overloaded | 429 rate limit | |
|---|---|---|
| Whose problem | the service is saturated, everyone is affected | your organisation crossed a line |
| Counts against your quota? | No | it is the quota |
retry-after | not guaranteed | present on an ordinary throttle; absent when allowance is exhausted |
| Levers you hold | None. Lower concurrency, more caching, a higher tier — none of it moves this | concurrency, caching and tier all work |
| Recovers when | upstream capacity catches up | seconds to minutes for a throttle; at the stated reset for exhaustion |
| What to do | wait, switch model, or let it keep retrying | see 429 troubleshooting |
One counter-intuitive direction deserves its own line, because it sends people to entirely the wrong page: if you just ramped your usage up sharply and then started getting errors, it's more likely a 429 than a 529. The official documentation attaches this note to the 529 entry itself — a sharp increase in usage can hit acceleration limits, which return 429. So in the sentence "I scaled up and then it overloaded", the word "overloaded" is usually a misremembering. Read the status code, not the feeling.
Work through this order
1 · Confirm it's actually a 529#
"Overloaded" is a word that gets applied to any failure at all. Read the status code and error type first, because every step below depends on that call.
# <model id>: copy one from https://api.9coding.com/v1/models
curl -sS -D - -o /dev/null https://api.9coding.com/v1/messages \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "content-type: application/json" \
-H "anthropic-version: 2023-06-01" \
-d '{"model":"<model id>","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
| grep -iE 'http/|retry-after|request-id'Only a 529 is what this page is about. A 401 goes to 401 troubleshooting, a 429 to 429 troubleshooting, and nothing at all to connection errors.
2 · Don't stack a manual retry on top of the automatic one#
An HTTP 529 was retried with backoff before it ever reached your screen. Pressing enter again re-runs a hypothesis that was just falsified several times over.
Tell the two on-screen states apart first: a countdown with an attempt counter (Retrying in 8s · attempt 3/10) means it's working — leave it alone. An error printed with no countdown is the terminal state after the retry budget is gone.
3 · If it died mid-answer, that's the other path and it needs other handling#
Text stops partway, no countdown, no obvious error — that's usually the in-stream overloaded_error, not an HTTP 529. It's easy to recognise: some output already arrived, then it stopped dead.
Interactively, all you can do is resend. In your own integration it needs explicit handling, because code that only inspects the response status can't see it — the status is 200. Note too that a near-identical feeling with a completely different cause is a proxy idle timeout cutting a long-lived connection. To tell them apart, see streaming responses cut off midway: ask for a short answer, and if short answers complete while long ones always break, it's a timeout, not an overload.
4 · Switching to a comparable model is the only immediate fix#
A 529 is a capacity event, and capacity gets tight per model — at the same moment, a comparable model is often fine. This is the one action on this page that gets you working again without waiting.
/modelYour session is preserved; carry on where you left off. Model ids come from the model list, or read /v1/models directly.
5 · Unattended runs need a different setting, not a different attitude#
In CI jobs and long autonomous sessions, failing halfway costs far more than waiting. Claude Code has a switch for exactly this; per the official error reference it retries capacity errors indefinitely instead of failing once the default budget is spent:
export CLAUDE_CODE_RETRY_WATCHDOG=1It has one boundary you must know: it still fails immediately on a 429 that reports a spend limit or exhausted credits — because retrying that kind of error forever is only a slower way to fail. Related settings are CLAUDE_CODE_MAX_RETRIES (default 10) and API_TIMEOUT_MS. The defaults, the caps and the way they interact have all changed between versions, so check the environment variable reference for the version you're running.
6 · Make the wait observable instead of retrying blind#
A 529 carries no readable contract header like retry-after to tell you how much longer, so "try again" is an action with no information in it. What you can check is service status: start with the status page. Against Anthropic directly the official message points at its own status page; through any other endpoint it points at the host named in the message.
To report it, bring the request id — every response carries a request-id header and the error body repeats the same value. 9Coding's error responses carry it as (request id: 2026...). That id, plus a timestamp, the model name and the full error text, is what makes a single call findable. "It's overloaded" cannot be investigated.
When this isn't your problem
When these hold together, it's an upstream capacity event and nothing on your side will move it:
- other clients pointed at the same endpoint are failing in the same window,
- it started with no change at all to your workload,
- it recovered on its own without you touching anything,
- a comparable model works immediately.
The reverse is just as informative: if only your client is failing, and it started right after you changed something, it probably isn't a 529 at all — go back to step 1 and read the status code.
Related errors
- 429 Too Many Requests — you crossed a line, and you do hold levers
- Streaming responses cut off midway — same feeling, but a timeout rather than an overload
- Connection error — never connected at all, which is an earlier layer
- All errors — the full troubleshooting index