Troubleshooting · Availability

What 529 Overloaded actually means

It says the upstream is short on capacity right now — not that your request is wrong. Changing your code will not help; changing your retry strategy will.

#Claude API#529#Overloaded#Retry strategy

Four points

529

Upstream congestion

Returned when server-side capacity is tight. Unrelated to your key’s quota, your parameters, or your request body.

429

You are being rate limited

This is the one that means you exceeded your own rate or quota. 529 and 429 need different handling — do not share a code path.

Backoff

The only effective client-side move

Exponential backoff with jitter. Retrying immediately worsens the congestion and gets you rate limited sooner.

Multi-route

Structural mitigation

When the same work can land on a different upstream, one congested provider stops meaning downtime. The cost is accepting model differences.

How 529 differs from 429 and 503

529 means the server is overloaded right now — a capacity problem, usually temporary. 429 means you hit your own rate or quota ceiling — a quota problem. 503 generally means the service is unavailable or under maintenance. None of them means your request was malformed, but the handling differs: 529 calls for backoff and retry, 429 calls for slowing down or raising limits, 503 calls for waiting and watching the status page. Collapsing all three into one catch block is the most common mistake in error handling.

Why discussion picks up periodically

Whenever a new model ships or a large migration happens, upstream capacity tightens for a while and 529 discussion rises with it. These waves usually ease as capacity is added — but for someone on a deadline, waiting for a vendor to expand is not an available answer.

Diagnostic order

First

Confirm the status code really is 529 and not 429. The response bodies differ; count them separately in your logs.

Second

Check the vendor status page. If it is a broad incident, no client-side change is more than mitigation.

Third

Check whether your own retry logic is amplifying the congestion: no jitter, no ceiling, and immediate retry all amplify.

Before retrying, work out which code you actually got

What is confirmed

529 signals upstream capacity congestion and is unrelated to request content — this semantics is stated in vendor documentation. Exponential backoff with jitter is a widely validated client-side response.

Do not treat as fact

Claims that "529 is the vendor quietly throttling heavy users" have no supporting evidence and are not asserted here. The distinction between 529 and 429 is documented publicly, and conflating them leads you to the wrong fix.

Two responses

Client-side backoff only

Cheap to implement and measurably reduces failures. But while the upstream stays congested, all you can do is wait.

Let work land on multiple upstreams

One congested provider stops meaning downtime. The cost is accepting different model habits, and every route has its own failure modes.

Writing retries correctly

Three points. First, exponential backoff rather than a fixed interval: wait a second, then double each time. Second, add random jitter — if every client backs off by the same amount they retry in a synchronised wave, which prolongs the congestion. Third, set ceilings on both retry count and total wait, or a single congestion event will let your task queue grow without bound. Separately, when a streaming request breaks mid-way, do not blindly retry from the start; first check whether what you already received can be continued.

What QCode can and cannot do here

What it can do: one key lets you switch to another model family during congestion instead of waiting for a single upstream to recover. What it cannot do: we are not the vendor and cannot change upstream capacity. And to be explicit — we have failed requests too. Over the past 7 days the failure mode we observed on our side was predominantly 502 at the gateway, with 0 instances of 529. A service that markets itself as failure-free is usually just not publishing its failure data. What we offer is multiple routes and inspectable failure records, not a promise of flawless service.

FAQ

Should I change my request parameters when I get a 529?

No. 529 is unrelated to request content; changing max_tokens, model parameters, or trimming the prompt will not make it go away. Change the retry strategy instead.

Can I use the same retry logic for 529 and 429?

Not advisable. 529 warrants backing off and retrying the same request; 429 means you need to lower your send rate or raise your limits, and blind retries keep tripping the limiter.

How long should I back off?

A common pattern is one second, doubling each attempt, with random jitter and ceilings on both retry count and total wait. The exact numbers depend on how much latency your task tolerates.

What if a streaming request hits 529 mid-way?

First check whether what you already received is usable. Continue if you can; retry the whole thing only if you cannot. Blindly restarting duplicates billing and adds to the congestion.

Does QCode get 529s?

Upstream congestion is real and we are not immune to it. In our own observations over the past 7 days our failures were predominantly 502, with 0 instances of 529. What we can do is let the same work move to another model family — not promise that failures will not happen.

Does multi-route mean no single point of failure?

No. Multiple routes lower the probability that one outage stops your work, but each route has its own failure modes and the routing layer itself can fail. It is mitigation, not elimination.

Sources

Status-code semantics follow each vendor’s official API documentation. This page deliberately cites no third-party availability percentages — such figures move over time and we have no authoritative independent measurement to point to.

When one route is congested, take another

One key across seven model families — switch and keep going when a route is under pressure.

Start free Browse models See plans