# Claude Code 529 Overloaded: What It Retries For You, and What It Won't

> A 529 isn't your usage limit and doesn't touch your quota. Claude Code already retried ten times before it told you. The useful question is which failures it retries automatically, which it deliberately doesn't, and the one environment variable that stops an unattended run dying on a transient capacity blip.

By Tahir Nazir · Published 2026-08-27 · Updated 2026-10-08
Canonical: https://www.its-tahir.com/blog/claude-code-529-overloaded-retry-behaviour

**A Claude Code 529 is not your usage limit, and it does not count against your quota.** It means the API is at capacity across all users right now — nothing is wrong with your account, your key, or your request — and because capacity is tracked per model, switching with `/model` is a better first move than retrying.

**It has already been retried.** By the time an overloaded error reaches you, Claude Code has tried up to ten times with exponential backoff:

```text
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.
```

So hammering the same prompt achieves nothing except joining the queue behind everyone else doing the same thing. The useful moves are different.

## Switch model before you retry

Capacity is tracked **per model**. A 529 on one model doesn't mean the others are saturated, so `/model` is a more productive response than retrying:

```bash
/model
```

This is the single highest-value thing in this post if you're blocked right now. Most people retry the same model repeatedly because the error doesn't mention that capacity is per-model.

## What gets retried automatically, and what doesn't

Transient failures are retried **up to 10 times with exponential backoff** before anything surfaces. Knowing the boundary tells you whether waiting will help.

**Retried for you:**

- Server errors, overloaded responses and timeouts that arrive *before any response has streamed*
- Connections dropped before Claude completes any part of its response, thinking included
- Stalled streams where nothing has arrived yet
- Temporary 429 throttles
- Requests exceeding the context limit — retried with a reduced `max_tokens`

**Deliberately not retried:**

- **TLS certificate validation failures** — reported on the first attempt so you can fix them immediately rather than watching ten silent retries
- **Mid-stream failures after Claude has started text or tool calls** — the completed work is kept instead
- **Failures arriving after the response finished** — the response is kept and the turn ends normally
- **Policy check denials** — the denied request is never re-sent to the same model or a fallback
- **Spend-limit 429s** — a gateway marks these `x-should-retry: false`, and they aren't capacity problems

That mid-stream rule is the one people misread as a bug. If Claude got halfway through and the connection died, you'll see something like:

```text
API Error: Connection lost mid-response. The response above may be incomplete.
```

The completed work was kept rather than discarded to start over. Reply `continue` and it resumes from the last completed block. In non-interactive mode with `-p`, it does that automatically **up to three times** before giving up.

While it is retrying, the spinner tells you where you are:

```text
Retrying in Ns · attempt x/y
```

And if nothing arrives for **20 seconds** while a request is pending, you get a network hint rather than silence. (During advisor review that banner waits 90 seconds instead, because advisors legitimately take longer.)

## The flag that keeps unattended runs alive

This is the part missing from most 529 write-ups, and it's the direct answer to [issue #60577](https://github.com/anthropics/claude-code/issues/60577) — transient capacity errors aborting long-running tasks with no auto-recovery.

If you run unattended — scheduled jobs, CI, long agentic tasks you walk away from — ten retries is not enough, because a capacity blip can outlast the backoff window. Set:

```bash
CLAUDE_CODE_RETRY_WATCHDOG=1
```

In unattended sessions that retries **429 and 529 capacity errors indefinitely**, and raises the retry count for other transient errors to **300**, which is roughly three hours of backoff. It also removes the `CLAUDE_CODE_MAX_RETRIES` cap entirely.

The related knobs:

| Variable | Default | What it does |
| --- | --- | --- |
| `CLAUDE_CODE_MAX_RETRIES` | 10 | Retry attempts. Capped at 15 as of v2.1.186. |
| `CLAUDE_CODE_RETRY_WATCHDOG` | unset | Set to `1` for indefinite capacity retries in unattended runs. |
| `API_TIMEOUT_MS` | 600000 | Per-request timeout — 10 minutes. |

Don't set the watchdog for interactive work. Sitting through three hours of backoff at your keyboard is worse than seeing the overloaded error and switching model.

## `Request timed out` is a different problem

Ten minutes is the default per-request timeout. If you're hitting it, the cause is usually one of three things, and only one is fixed by raising the limit:

- **The model is generating a very large response** — break the work into smaller prompts instead
- **A slow network or proxy** — this is the case where raising `API_TIMEOUT_MS` is the right call
- **High load** — retry, or switch model

Reaching for `API_TIMEOUT_MS` when the real cause is an oversized task just means waiting longer for the same failure.

## Session limits look similar and aren't

A capacity error and a usage limit produce different messages, and conflating them sends you down the wrong path:

```text
You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm
```

Session and weekly limits are **shared across all models**, so `/model` won't rescue you there. But `Opus limit` and `Sonnet limit` apply only to that model family — switching does work for those. Usage counts against session and weekly allowances **simultaneously**.

Since **v2.1.234**, an interactive session on a claude.ai subscription can wait it out instead:

```text
Usage limit reached · continuing automatically at 3:45pm · esc to cancel
```

Press `Esc` at an empty prompt to cancel the wait. You can toggle it under `/config` → **Continue automatically at usage limit**, and separately in the Desktop app's Code tab — they're independent settings.

If limits are what you keep hitting rather than capacity, the causes are worth understanding separately; I went through them in [why Claude Code burns tokens while you're not even using it](/blog/why-claude-code-uses-so-many-tokens).

## A quick triage order

1. Read the message. Capacity (`529`), rate limit (`429`), timeout and usage limit are four different problems.
2. If it's a 529 overloaded error — `/model` first, don't retry the same one.
3. Check [status.claude.com](https://status.claude.com) for an active incident before debugging your own setup.
4. If it happened mid-response, reply `continue` rather than re-running the whole task.
5. For unattended runs, set `CLAUDE_CODE_RETRY_WATCHDOG=1` so a blip doesn't kill a three-hour job.
6. Run `/status` to confirm which credential is actually active — a 429 often traces to the wrong one.

**Key takeaways**

- A 529 overloaded error is a capacity error, not a usage limit, and does not count against your quota.
- Capacity is tracked per model, so /model is more likely to unblock you than retrying the same one.
- An overloaded error means it already retried up to 10 times with exponential backoff before telling you.
- Mid-stream failures are deliberately not retried — completed work is kept, and 'continue' resumes from the last block.
- CLAUDE_CODE_RETRY_WATCHDOG=1 retries capacity errors indefinitely in unattended runs. Don't use it interactively.

The pattern worth internalising: most of these errors are already being handled for you, and the ones that aren't are unhandled *on purpose* — because retrying would throw away work or re-send something that was denied. Knowing which bucket you're in turns a vague "the API is broken" into a two-second decision.

If your error isn't a capacity problem at all, [every Claude Code error and its fix](/blog/claude-code-troubleshooting) sorts the rest by cause, with a one-line answer for each.

If the symptom is the CLI feeling sluggish rather than erroring, that's a separate class of problem — [Claude Code slow, hanging, or eating memory](/blog/why-claude-code-is-slow-hanging-or-eating-memory) covers the silent ones, including a search failure that reports itself as healthy. Managing what these tools carry into a session is the problem [ContextZero](/work/contextzero) came out of.

## FAQ

### Does a 529 error use up my usage limit?

No. A 529 is a capacity error, not a usage limit, and it does not count against your quota. It means the API is at capacity across all users at that moment. It is also not an account problem or a bad request.

### Should I keep hitting retry when I see a 529?

Not manually. Claude Code has already retried several times with exponential backoff before it shows you that message, so an immediate manual retry just queues behind everyone else doing the same thing. Because capacity is tracked per model, switching with /model is more likely to work than retrying the same one.

### How do I stop an unattended Claude Code run dying on a transient 529?

Set CLAUDE_CODE_RETRY_WATCHDOG to 1. In unattended sessions that retries 429 and 529 capacity errors indefinitely, and raises the retry count for other transient errors to 300, which works out to roughly three hours of backoff. It also removes the CLAUDE_CODE_MAX_RETRIES cap.

### Why did Claude Code stop mid-response instead of retrying?

That is deliberate. Once Claude has completed a block of text or a tool call, Claude Code keeps the completed work rather than throwing it away to retry. Reply with continue and it picks up from the last completed block. In non-interactive mode with -p it does this automatically, up to three times.

## Sources

- [Error reference — Claude Code docs](https://code.claude.com/docs/en/errors)
- [Environment variables — Claude Code docs](https://code.claude.com/docs/en/env-vars)
- [Transient 529 Overloaded errors abort long-running tasks with no auto-recovery (issue #60577)](https://github.com/anthropics/claude-code/issues/60577)