`overloaded_error` — an HTTP 529, or an error that arrives after a 200

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

If you pasted that line, or its overloaded_error half, into a search box, your agent’s turn probably ended there, mid-task, with whatever output it had got so far. Here is what Anthropic’s own docs say the error means, read off them today. They describe two different ways it reaches you, and the fix depends on which one you got.

What the vendor says it means

The errors reference, at platform.claude.com/docs/en/api/errors, lists it with its status code:

529 - overloaded_error: The API is temporarily overloaded.

and adds a warning directly beneath it:

529 errors can occur when the API experiences high traffic across all users.

Read the last four words twice. This is not your quota. Your own limits have a different code on the same page: 429 - rate_limit_error, “Your organization has hit a rate limit”. The same warning also says that “In rare cases, if your organization has a sharp increase in usage, you might see 429 errors because of acceleration limits on the API.” So the number carries the diagnosis: 529 means load on the service, 429 means usage on your account. If what you are holding is a 429, this page is about the wrong error.

The two ways it arrives

As a status code, on a request that failed. The errors reference says: “The official SDK automatically retries transient failures (such as connection errors, rate limits, and 5xx server errors) with exponential backoff, twice by default, honoring the retry-after header when present.” A 529 is a 5xx. So if a plain, non-streaming call through the official SDK raised it, and you never changed the retry setting, the default retries had already run before it reached your code.

As an event, inside a stream that had already succeeded. This is the one that ends agent turns. The same page says:

When receiving a streaming response over server-sent events (SSE), an error can occur after the API returns a 200 response. In that case, error handling doesn’t follow these standard mechanisms.

The streaming guide, at platform.claude.com/docs/en/build-with-claude/streaming, names this exact case: “during periods of high usage, you may receive an overloaded_error, which would normally correspond to an HTTP 529 in a non-streaming context”. Its example is the line at the top of this page:

event: error data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

Put those together and you get the usual shape of the complaint. The request returned 200, tokens started arriving, and partway through the turn an error event arrived in place of the rest. An agent loop that takes a 200 as success, and the end of the stream as the end of the turn, will record a finished turn that is really a cut-off one.

The fix

Handle the error event as its own branch. Do not let the stream simply end. When an error event arrives, mark the turn as not completed, whatever was already received. The errors reference says this case “doesn’t follow these standard mechanisms”, so do not assume the SDK retry described above already covered it. Check that your loop actually sees the event.
Retry the turn, not the tail. Keep the exact request you sent. On an overloaded_error, throw away the partial assistant output, and any tool calls it had started, then wait and send the same request again. A half-finished turn written into your history looks like a real answer to the next step.
Back off, and do not shrink your own traffic for it. The vendor ties 529 to load across all users. Waiting is what helps here; cutting your own concurrency is the fix for a 429, not a 529. Honour retry-after if the response carries it, which is what the reference says the SDK does.
Give expensive turns more retries. The reference says the SDK client accepts max_retries (maxRetries in TypeScript) “to configure or disable this behavior”. If losing a turn costs you minutes of agent work, raise it. If your agent has its own retry loop, make sure the two are not stacking.
Branch on the type, not the message. Match error.type == "overloaded_error", not the word Overloaded. The reference advises: “Catch the SDK’s typed classes rather than string-matching error messages”. It also warns that “it is possible that the type values will grow over time”, so send unknown types to a default branch instead of crashing on them.

What makes this error expensive is not the error. It is how much finished work sits in the turn it cuts off. A loop that saves its state after every completed turn loses one turn to a 529. A loop that saves only at the end loses the whole run. The first fix is in your error handling. The lasting one is in how much each turn is asked to carry.

What is behind this site

There is a written guide: the step-and-turn arithmetic as a formula you can run against a brief before you launch it, why raising a cap does not finish the job, and batch.py, one standard-library file that collapses a per-item loop into a single pass. It is $19, on a Gumroad storefront. One working way to pay today is 19 USDC on Base: you email the transaction hash and the guide is delivered by email. This page is free, ungated, and sells nothing on its own.

The short version: overloaded_error is Anthropic’s HTTP 529, “The API is temporarily overloaded.”, and the vendor says it can occur “when the API experiences high traffic across all users”. It is not your rate limit; that is 429. On a plain request the official SDK retries 5xx errors twice by default. In a stream it can arrive as an error event after a 200, and the vendor says that case does not follow the standard handling. So catch the event, throw away the partial turn, back off, and send the same request again.

Nearby

stop_reason: pause_turn — a Claude turn that stops on purpose, at the server-side tool loop’s iteration limit.
stop_reason: max_tokens — a truncated response on an HTTP 200, and why the cap may not be yours.
stop_reason: refusal — a safety decline delivered as an HTTP 200 with empty content.
stop_reason: end_turn and stop_sequence — the two stop values that do not ask you to send another request.
Why an agent run dies before its timeout — the same kind of wall read off the clock, with the arithmetic that predicts it.

This page counts anonymous readership with one counter, the file at /measure.js, and each of the events below is sent at most once per load. Once the page is ready it sends one view event. With it go the page path, the domain of the page you came from — only the domain, and nothing at all if you came from this site — how long the page has been open, counting only the time it was actually in front of you and not the time it sat in a background tab, whether you have scrolled, and any campaign or outreach code in the link you followed. A second event, which we call a human candidate, is sent only once the page has also received a real input event from you — a mouse movement, a touch, a scroll or a key press — and has been visible in the foreground for ten seconds in all; a program that fetches the page, or opens it and sits there, cannot produce one. A third, “engaged”, is stricter still: it is sent only after the human-candidate event, once the page has been in front of you for ninety seconds in all and you have scrolled far enough to reach a marker we put where the explaining part of this page ends; a reader who stops short of that marker never produces one. The second and third events carry the same fields as the first. If you switch away from the tab or close it, an event that has just become due may be sent as you leave. If this page has a button or a copy control that says it records a click, pressing it sends the name of that event and nothing else. Following a link to buy the guide sends one further event, also at most once per load, carrying that event’s name and a single word for which of the two checkouts you were sent to — the Gumroad listing or the payment page on this site — and nothing else: not the address you followed, not which page you were reading, not how long you had been there. Everything is sent to this site only, with no cookie attached. No cookie is read or written, nothing is put in your browser’s local or session storage, and no identifier is made from your device. Earlier versions of this page kept the campaign codes of your first visit in local storage under the name llab_attr; this page neither reads nor deletes that entry, so if it is there it stays until you clear this site’s data. An outreach code is minted per recipient, which would let us tell one reader from another; it is sent with each event and, unlike on earlier versions of this page, it is no longer removed from the address bar after it is read — if you copy the address, the code goes with it. Earlier versions also asked this domain for Vercel’s analytics script at /_vercel/insights/script.js, which on 26 September 2026 returned HTTP 404 on every host we publish; this page no longer asks for it. Your browser and the network attach things the page does not send: the identification string your browser gives, your IP address and the time of the request. The host that serves this page keeps its own request logs; those are its record and not ours.