"529 Overloaded" error in Claude Code: what it is and what actually fixes it

The "API Error: 529 Overloaded" message shows up in the middle of a Claude Code session, and the natural reaction is to hit enter again. It does not help, and your quota is not what ran out: the Anthropic API is temporarily overloaded, and the official documentation says so in plain words. More than that, the CLI is already retrying on its own while you stare at the screen. The real damage is somewhere else, in the agents you launch in parallel.

What does "529 Overloaded" mean?

It means the Anthropic API is temporarily overloaded. It is not an error in your code, your key, or your plan.

In the official Claude API error documentation, code 529 carries the type overloaded_error and this literal definition: "The API is temporarily overloaded". The warning right below settles the question: "529 errors can occur when the API experiences high traffic across all users". High traffic across everyone, not yours.

The response arrives in this shape:

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "Overloaded"
  },
  "request_id": "req_011CeME4MStM56TRJaC3dWRJ"
}

Keep the request_id. It comes with every API response, also in the request-id header, and it is what Anthropic support asks for to trace a specific request.

Is it my quota or is it Anthropic?

It is Anthropic. The code that means "your quota" is a different one: 429. Mixing them up makes you fix the wrong thing, switching models or plans over a problem that is not yours.

Code	Type	Whose problem it is	What to do
429	rate_limit_error	Yours. The organization hit a rate limit or a spend cap	wait out the window, review the limit or plan
529	overloaded_error	Anthropic's. High traffic across all users	let the automatic retry do its job
500	api_error	Anthropic's. Unexpected internal error	retry with exponential backoff; if it persists, contact support with the request_id
504	timeout_error	Request took too long	use the streaming Messages API

To confirm it is general and not just you, check status.claude.com before changing any configuration.

Do I need to keep retrying?

No. The CLI already does it for you, and it shows on screen how many attempts it has made.

The line you see, recorded in issue #91817 of the official repository, is this one:

✻ 529 Overloaded · Retrying in 4s · attempt 6/10

That is up to 10 attempts, with growing waits between them. Closing the terminal and reopening it mid-way throws away the attempts already made and restarts the count from zero, which is the opposite of what you want.

If you call the API directly through the SDK instead of the CLI, the default is more conservative. The official SDKs retry transient failures with exponential backoff twice by default, honoring the retry-after header when it is present. You can raise that on the client:

client = anthropic.Anthropic(max_retries=5)

Why do my parallel agents all fail together?

Because they leave together. When an orchestrator fans out several agents at once, every first request hits the API at the same instant, and a momentary overload takes down the whole batch instead of one or two.

The pattern is described in issue #90043, whose title is already the diagnosis: "Fan-out launches agents without stagger, causing correlated 529 failures". With no jitter between launches, the failures become correlated.

Anthropic's own documentation recommends the opposite, when discussing acceleration limits: "ramp up your traffic gradually and maintain consistent usage patterns". Ramp up instead of spiking. In practice, spreading the launches is enough:

import random, time

for task in tasks:
    launch(task)
    time.sleep(random.uniform(0.5, 2.0))

Two seconds of launch delay cost less than redoing the whole batch.

How do I avoid losing the work when a subagent dies?

This is the hidden cost of 529, and the most expensive one. When a background subagent dies with this error, it returns no partial result: the task comes back as failed and the only way forward is to relaunch from zero. Issue #89267 describes exactly that, and the second run repeats, and pays again for, all the work the first one had already done.

Until that behavior changes, the defense is architectural: break a long task into steps that write results to disk as they finish, instead of one hour-long task that only delivers at the end. That way a 30-second overload costs you one step, not the entire task.

The same care applies to automation running unattended: a scheduled task that fails with 529 can still count as a finished run and fire a success notification, the behavior reported in issue #92423. If your cron trusts the exit code, also check whether anything was actually delivered.

And when 529 comes back every single day?

At that point it is not an incident, it is a dependency. Everything above still applies, but none of it changes the fact that the queue is controlled by another company.