Claude Code stops mid-task and prints something like:
API Error: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}
You may also see it phrased as "the API is temporarily overloaded and is temporarily unavailable", or simply as repeated 529 Overloaded failures during a long operation.
The important thing to know first: you did nothing wrong. HTTP 529 is Anthropic's signal that the API is at capacity right now. It is not caused by your prompt, your account, your installation or your configuration.
Why This Happens
Anthropic's API returns 529 when upstream capacity for the model you requested is saturated. It is a load-shedding response — the service declines the request rather than queueing it indefinitely.
Claude Code already handles the transient case for you. It retries overloaded responses with backoff, including mid-stream, before showing you anything. So when a 529 does reach your terminal, it means the retries were refused as well and the overload outlasted the retry budget.
Three factors make you more likely to see it:
- Peak demand windows. Overloads cluster around US working hours and immediately after a new model release.
- The newest or largest model. Capacity pressure is per-model, and the most capable model in the family is usually the most contended.
- High concurrency on your side. Parallel subagents, background tasks and multiple open sessions each add requests in flight, and each one is another opportunity to hit a saturated backend.
529 is not a rate limit
This distinction matters because the fixes are opposite:
| 429 rate limit | 529 overloaded | |
|---|---|---|
| Meaning | You used your allowance | The service is at capacity |
| Scope | Your account | Everyone on that model |
| Retry immediately? | No — wait for reset | Yes — often succeeds in seconds |
| Fixed by upgrading? | Yes, a higher tier raises the ceiling | No, but higher tiers get priority |
If you are actually hitting 429s, see Claude Code rate limits and reset times instead — the guidance there does not apply here.
Fix 1: Retry
Because a 529 is transient, the simplest response is usually the right one. Wait ten to thirty seconds and send the message again. Overload spikes frequently clear that fast.
If you are inside a long task, resend the last instruction rather than restarting the session — your context is intact.
Fix 2: Set a Fallback Model
This is the fix that stops 529s from interrupting you. Claude Code can switch models automatically when the primary is overloaded or unavailable:
claude --fallback-model claude-sonnet-5
The option accepts a comma-separated list, tried in order:
claude --fallback-model claude-sonnet-5,claude-haiku-4-5-20251001
To make it permanent, set fallbackModel in your settings file rather than passing the flag each time. Note that the command-line --fallback-model takes precedence over the settings value when both are present. See where configuration files are stored for the settings locations.
Fix 3: Switch Models Manually
Mid-session, switch with:
/model
Because capacity is tracked per model, a smaller or older model in the family is often serving normally while the newest one is saturated. Switching takes effect on your next request and keeps the conversation intact. Switching models covers what you give up in each direction.
Fix 4: Reduce Concurrency
If you are running parallel subagents, background tasks or several Claude Code windows, cut back during an overload. Each in-flight request is an independent chance to be refused, and one request at a time is meaningfully more likely to get through than six.
Let running background tasks finish before starting new ones, and postpone wide fan-out work — the kind that spawns many agents at once — until capacity recovers.
Fix 5: Check for an Incident
Before spending time on workarounds, confirm whether this is a blip or an outage:
https://status.anthropic.com
If an incident is posted for the API, no amount of local configuration will help. Switch to a fallback model if one is unaffected, or come back when the incident closes. If nothing is posted, you are almost certainly on the short-lived spike path and a retry will work.
Fix 6: Rule Out a Proxy
If 529s appear constantly rather than in bursts, and only for you, suspect something between you and the API. Corporate proxies, gateway products and third-party API routers can return or relay 5xx responses of their own.
Test a direct connection:
# Check what proxy settings are active
env | grep -i proxy
# Temporarily bypass them
unset HTTP_PROXY HTTPS_PROXY
claude
If the errors stop without the proxy, the problem is your network path rather than Anthropic's capacity, and the proxy configuration is what needs attention.
Verify the Fix
Send a short message such as hello and watch for a normal response. A clean reply means capacity is available again.
To confirm a fallback model is configured, check that Claude Code reports the model it is using:
/status
If you are still seeing 529s after switching models and confirming no proxy is involved, it is an upstream capacity issue and waiting is the only remaining option.
Prevention
- Configure a fallback model once. It converts an interruption into an automatic model switch you may not even notice.
- Do not treat the newest model as the default for everything. Routine edits and refactors run fine on a smaller model that is far less contended.
- Keep concurrency modest. Parallel agents are powerful, but during busy periods they multiply your exposure.
- Schedule long unattended runs off-peak. Large batch work is far less likely to be interrupted outside US business hours.
- Do not build tight retry loops in scripts. Claude Code already backs off correctly; wrapping it in an aggressive retry adds load without improving your odds.
Related Guides
- Claude Code rate limits and reset times — the 429 case, which needs the opposite response
- Switching models in Claude Code
- Fixing a frozen or stuck Claude Code session