Claude Code "model overloaded": what to do

What a Claude Code model overloaded error actually means

A model overloaded error in Claude Code means Anthropic's API is temporarily out of capacity. The documented failure is HTTP 529 with the error type overloaded_error and the message The API is temporarily overloaded. Your billing is fine and you have not hit a usage limit. The request simply did not get served, so the session stops mid-turn.

That distinction changes what you do next. An overload is fixed by retrying, because the load sits on Anthropic's side and it passes. A usage limit is not fixed by retrying, because retrying returns the same answer until a window resets or you raise a limit. Picking the wrong response costs you either time you did not need to lose or a pile of failed requests.

Claude Code is a client of the same Messages API that any script or SDK calls, so the failures underneath it are that API's documented failures. Every status code, type string and header name on this page comes from the Claude API errors reference and the rate limits reference, checked in August 2026. If the connection between the CLI and the API is new to you, Claude Code is a terminal client for the same Messages API the SDKs use.

The three failures that stop a turn and look alike

• HTTP 529, type overloaded_error. Anthropic's capacity, not yours. Retry with backoff.
• HTTP 429, type rate_limit_error. Your organization's rate limit, its usage tier's monthly spend cap, or a spend limit on the Claude Code workspace. Some of these are worth retrying and one of them never is.
• A subscription usage limit. Pro and Max plans meter usage on their own schedule. That system is separate from the HTTP status codes above.

The wording on screen does not always spell out which one you hit, so work from the status code and the response headers instead of from the message text.

HTTP 529 overloaded_error: the API is temporarily overloaded

The documented description is one sentence: The API is temporarily overloaded. The warning on the same page names the cause. 529 errors can occur when the API experiences high traffic across all users. So the trigger is aggregate load, not anything you configured on your account.

The error body follows the documented shape: a top-level error object holding a type and a message, plus a request_id you can quote to support.

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "The API is temporarily overloaded."
  },
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWG"
}

Two checks tell you quickly whether the problem is broad. Open status.claude.com, which lists Claude Code as its own component next to the Claude API, so a degraded component there means the problem is not local to you. If you also hold an API key, run the curl command further down and watch for a 529 on a request that has nothing to do with your Claude Code session.

Note what a 529 is not attached to. It is not tied to your key or your plan, so rotating a key, logging out or moving to another machine changes nothing about it.

HTTP 429 rate_limit_error: one code, several causes

The documentation describes 429 as covering more than one situation: your organization has hit a rate limit, reached its usage tier's monthly spend cap, or reached a spend limit on the Claude Code workspace. Same code, same type string, different remedies.

Rate limits themselves are set per organization and per model class, measured in requests per minute (RPM), input tokens per minute (ITPM) and output tokens per minute (OTPM). They use a token bucket, so capacity refills continuously rather than resetting on the hour. They are also enforced over shorter windows than the names suggest. The documentation notes that a rate of 60 requests per minute might be enforced as 1 request per second, which means a short burst can trip a limit you are nowhere near on average.

The header that decides your next move is retry-after. It holds the number of seconds to wait, and the reference is explicit that earlier retries will fail. A 429 carrying retry-after is a wait. A 429 without it is something else, covered in a moment.

One caching note, because a coding agent resends conversation context on every turn: for most models only uncached input tokens count toward ITPM, and cache_read_input_tokens does not count at all. That is why prompt caching raises the throughput you get out of the same limit without any limit increase.

A limit you set yourself behaves differently again. When usage reaches an organization or workspace spend limit you configured in the Console, the API returns HTTP 400 with type invalid_request_error and a message beginning You have reached your specified API usage limits. The Claude Code workspace is the documented exception: its limits are checked separately, and requests over that workspace's limit can return a 429 that does carry retry-after.

Why a sharp ramp in your own traffic returns 429

This is the part most troubleshooting pages leave out. The documented warning 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. The remedy it gives is to ramp up your traffic gradually and maintain consistent usage patterns.

Read that next to the 529 rule and a useful asymmetry appears. Heavy load across all users shows up as 529. A sharp ramp in your own load can show up as 429. So a wave of 429s arriving the moment you start ten Claude Code sessions at once, or kick off a scripted batch of agent runs, is far more likely to be your own ramp than an outage, even though it feels like everyone else's fault.

The practical version: bring parallel sessions up over a few minutes instead of all in one second, and keep a scheduled job's concurrency steady between runs rather than doubling it each time. A stable request rate is what the documentation asks for, at the same average volume.

The 429 that never succeeds no matter how long you wait

Reaching your usage tier's monthly spend cap also returns 429 with type rate_limit_error, and this one does not clear on retry. The documented response looks like this.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "You have reached your API usage limits: your organization has crossed its monthly API usage threshold, set based on your organization's API tier. You will regain access on 2026-09-01 at 00:00 UTC.",
    "details": { "error_code": "enforced_spend_limit_reached" }
  },
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWG"
}

Two markers identify it. The response has no retry-after header, so every retry fails until access resumes, including the automatic retries your SDK performs. On the Messages API, error.details.error_code is enforced_spend_limit_reached, which is the reliable way to tell this apart from an ordinary rate limit. The message text also names the moment access returns, so you do not have to guess.

Usage pauses until 00:00 UTC on the first day of the next month unless you request a higher limit sooner. As of August 2026 the documented monthly spend caps are 500 USD on the Start tier, 1,000 USD on Build and 200,000 USD on Scale, with no cap on the Custom tier. Moving to a higher tier restores access.

If your retry loop treats every 429 the same, this is the case where it burns its whole budget for nothing. Read the body before you sleep.

Subscription usage limits are a different system

If you run Claude Code on a Pro or Max subscription rather than an API key, none of the tier machinery above applies to you. There is no organization tier and no monthly spend cap. Subscription usage is metered on its own schedule, and hitting that limit is a different event with a different remedy, which is why it has its own pages: how Claude's subscription usage limits are measured and what to do once you have actually hit one.

One more thing stops a turn without being an overload or a plan limit: the cap on how many tool calls a single turn may make. The session halts mid-work, which looks similar on screen. Rule out that case before you blame capacity.

The short test is this. A 529 or a 429 is an HTTP failure you can reproduce and see with curl. A subscription limit is not.

How to see the status code and headers yourself

This only works if you hold an API key. A Claude Code login on a Pro or Max subscription does not put one in your environment, so the command below returns an authentication error instead of anything useful.

curl -sS -o /tmp/body.json -D /tmp/headers.txt -w '%{http_code}\n' \
  https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

A healthy call prints 200. Anything else is the number you actually need. Then read the two headers that matter, plus the parts of the body that identify the case.

grep -iE '^(retry-after|request-id):' /tmp/headers.txt
jq '.error.type, (.error.details.error_code // "none"), .request_id' /tmp/body.json

On a healthy 200 there is a request-id line, no retry-after line, and the jq output is nulls, because a success body carries no error object. On an ordinary rate limit you get a retry-after line and "rate_limit_error". On the spend cap case you get "rate_limit_error" with "enforced_spend_limit_reached" and no retry-after line at all. On an overload you get "overloaded_error".

Retry the right way, and what the SDKs already do

Start from the documented baseline. The official SDKs automatically retry transient failures such as connection errors, rate limits and 5xx server errors, with exponential backoff, twice by default, and they respect the retry-after header when it is present. A 529 is a 5xx, so it is already inside that set. Each SDK client takes a maximum-retries option so you can change or disable the behaviour.

In Python the option is max_retries and the default is 2.

import anthropic

client = anthropic.Anthropic(max_retries=5)

try:
    message = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello, Claude"}],
    )
    print("ok", message._request_id)
except anthropic.RateLimitError as e:
    print("429", e.status_code, e.response.headers.get("retry-after"))
except anthropic.InternalServerError as e:
    print("5xx, which is where 529 lands", e.status_code)
except anthropic.APIConnectionError as e:
    print("never reached the API", e.__cause__)

Catch RateLimitError before InternalServerError, because the more specific class has to come first or the broader one swallows it. Raising max_retries helps with a 529 and with an ordinary rate limit. It does nothing for a spend cap 429, because there is no retry-after to honour and nothing changes inside the current month. You can also set the option for one call with client.with_options(max_retries=5).messages.create(...), which is useful when a single request in a batch job deserves more patience than the rest.

If you drive the API from a shell script instead, the same logic is a short loop. It expects your request body in request.json.

#!/usr/bin/env bash
# Retry one Messages API call on 429 and 5xx. Give up at once on a spend cap.
set -u
attempt=0
max_attempts=5

while [ "$attempt" -lt "$max_attempts" ]; do
  code=$(curl -sS -o /tmp/body.json -D /tmp/headers.txt -w '%{http_code}' \
    https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d @request.json)

  if [ "$code" = "200" ]; then
    echo "ok"
    exit 0
  fi

  case "$code" in
    429|500|502|503|504|529) ;;
    *) echo "not retryable: HTTP $code"; jq -r '.error.message' /tmp/body.json; exit 1 ;;
  esac

  if [ "$(jq -r '.error.details.error_code // ""' /tmp/body.json)" = "enforced_spend_limit_reached" ]; then
    jq -r '.error.message' /tmp/body.json
    exit 1
  fi

  wait=$(grep -i '^retry-after:' /tmp/headers.txt | tr -d '\r' | awk '{print $2}')
  if [ -z "$wait" ]; then
    wait=$(( 2 ** attempt + RANDOM % 3 ))
  fi

  attempt=$(( attempt + 1 ))
  echo "HTTP $code, attempt $attempt of $max_attempts, sleeping ${wait}s"
  sleep "$wait"
done

echo "gave up after $max_attempts attempts"
exit 1

The request id, and when to contact support

Every API response includes a request-id header holding a value such as req_018EeWyXxfu5pfWkrYcMdjWG, and the same value appears as the request_id field in error bodies. Include it when you contact Anthropic support about a specific failure. It is what lets someone find your exact request rather than search by description.

The Python and TypeScript SDKs expose it as a _request_id property on top-level response objects. To read it, or any other response header, use the raw response accessor.

response = client.messages.with_raw_response.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(response.headers.get("request-id"))
message = response.parse()

While you are reproducing a failure, the Python SDK logs through the standard library logging module, and export ANTHROPIC_LOG=debug turns that on.

Pick the right destination. A 529 that persists long after the status page goes green is worth a support ticket with the request id attached. A spend cap 429 is not a support case first: use Request rate limit increase on the Rate limits page in the Console, because that is the control that restores access.

What not to do when the API is overloaded

• Do not rotate or swap your API key. The documented cause of a 529 is high traffic across all users, so a different key meets the same shortage of capacity.
• Do not retry faster. The retry-after definition states that earlier retries will fail, and on a 529 a tighter loop adds to the load that produced it.
• Do not raise a spend cap because of a 529. That is a different error in a different system. Read the status code before you touch billing settings.
• Do not treat every 429 as a wait. Check error.details.error_code first. If it reads enforced_spend_limit_reached, no amount of waiting inside the current month helps.

FAQ

Is a Claude Code model overloaded error a usage limit?

No. An overloaded message maps to HTTP 529 with the error type overloaded_error and the documented description The API is temporarily overloaded. The documented cause is high traffic across all users of the API, so it is a capacity shortage on Anthropic's side. Your plan and your billing are not involved, which is why the fix is to retry with backoff rather than to change a setting.

What is the difference between HTTP 529 and HTTP 429 from the Claude API?

529 carries the type overloaded_error and means the API is temporarily overloaded for everyone. 429 carries the type rate_limit_error and means your own organization hit one of its own boundaries: a rate limit, its usage tier's monthly spend cap, or a spend limit on the Claude Code workspace. The fastest test is the retry-after header. A rate limit 429 carries one and it gives the number of seconds to wait. The spend cap 429 carries none, and its body has error.details.error_code set to enforced_spend_limit_reached.

Why do I get 429 errors when Anthropic is not having an outage?

Because a sharp increase in your own usage can hit acceleration limits on the API. The documentation states that in rare cases an organization with a sharp increase in usage may see 429 errors for this reason, and the remedy it gives is to ramp up traffic gradually and maintain consistent usage patterns. Starting many Claude Code sessions at once, or firing a large scripted batch in one go, is exactly the shape of traffic that does it. Bring the load up over a few minutes and keep it steady between runs.

How long should I wait before retrying an overloaded request?

When the response carries a retry-after header, use that number of seconds, because retrying earlier is documented to fail. When there is no retry-after, back off exponentially and add a small random offset so that many clients do not all come back at the same instant. The official SDKs already retry twice by default with exponential backoff, so a plain script mostly needs to match that. Anthropic does not publish a fixed wait for a 529, so treat any specific number of seconds you read elsewhere as a guess rather than a rule.