Claude API 429 vs 529 — rate_limit_error vs overloaded_error

Quick answer

A 429 rate_limit_error means you exceeded a quota on your key or organization (requests or tokens per minute) — slow down and wait the number of seconds given in the retry-after header. A 529 overloaded_error means the upstream service is temporarily out of capacity — your quota is fine; retry with exponential backoff and jitter. Both are retryable, but the wait signal differs: a 429 tells you exactly how long to wait, a 529 does not.

Symptoms and what each error means

Both errors arrive as an HTTP status plus a JSON envelope. The error.type field is the portable signal — it survives every SDK and gateway, while headers can vary by hop.

// HTTP 429
{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "This request would exceed the rate limit for your organization..."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

// HTTP 529
{
  "type": "error",
  "error": { "type": "overloaded_error", "message": "Overloaded" }
}

Dimension	429 rate_limit_error	529 overloaded_error
Whose problem	Yours — your key/org hit a quota	Upstream — service-wide load spike
Trigger	Requests per minute, input/output tokens per minute, or daily token caps	High demand on the model fleet; unrelated to your account
Useful headers	retry-after, anthropic-ratelimit-*	Usually none
Nature	Deterministic — retrying instantly just burns more quota	Transient — usually clears in seconds
Correct response	Honor retry-after, then throttle at the client	Exponential backoff with jitter; optional model fallback

The response headers that matter

On a 429, the Anthropic API tells you exactly where you stand:

• retry-after — seconds to wait before the next attempt. This is the authoritative signal; sleeping for this value beats any guessed backoff.
• anthropic-ratelimit-requests-limit / -remaining / -reset — the request-count bucket.
• anthropic-ratelimit-input-tokens-* and anthropic-ratelimit-output-tokens-* — the token buckets. These drain much faster than request counts when prompts are large or max_tokens is high, which is why "I only sent five requests" can still 429.

Inspect them with a header dump:

curl -sS -D - -o /dev/null https://byesu.com/v1/messages \
  -H "Authorization: Bearer sk-YOUR_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":64,"messages":[{"role":"user","content":"Reply with the single word: ok"}]}'

A 529 typically carries no rate-limit headers — there is no quota to report, because the problem is capacity, not your usage.

What triggers each

429 causes:

• Burst traffic — parallel agent loops or batch jobs firing simultaneously against one key
• Token-bucket exhaustion — long prompts or high max_tokens draining input/output token quotas
• One key shared across several apps or teammates, each unaware of the others
• Daily token caps reached late in the day

529 causes:

• Demand spikes on a popular model (common right after a new model launches)
• Upstream fleet maintenance or partial degradation

Nothing you change on your side prevents a 529 — the only lever you own is how gracefully you retry.

Handling each one correctly

429 — honor retry-after, then throttle

import time
import anthropic

client = anthropic.Anthropic(
    api_key="sk-YOUR_TOKEN",
    base_url="https://byesu.com",  # Anthropic-native endpoint
)

try:
    message = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Summarize this changelog in three bullet points."}],
    )
except anthropic.RateLimitError as e:  # HTTP 429
    wait = int(e.response.headers.get("retry-after", "30"))
    time.sleep(wait)  # the server told you how long — believe it
    # then retry once

If 429s recur, the fix is architectural, not more retries: add a client-side limiter or queue, trim prompts, lower max_tokens, and give each app its own token so one consumer cannot starve the rest.

529 — exponential backoff with jitter

import random
import time
import anthropic

def call_with_backoff(client, max_attempts=5, **kwargs):
    for attempt in range(max_attempts):
        try:
            return client.messages.create(**kwargs)
        except anthropic.APIStatusError as e:
            if e.status_code == 529 or e.status_code >= 500:
                delay = min(2 ** attempt + random.uniform(0, 1), 60)
                time.sleep(delay)  # back off, with jitter to avoid retry stampedes
                continue
            raise  # other 4xx errors are not retryable — fix the request
    raise RuntimeError("Upstream still overloaded after retries")

The jitter matters: if every client retries at identical intervals, the synchronized wave re-overloads the upstream and prolongs the incident.

Let the SDK take the first pass

The official Anthropic SDKs already retry 429 and 5xx-class errors (529 included) with exponential backoff, honoring retry-after when present — the default is 2 retries, tunable via max_retries. Write your own loop only for behavior the SDK does not provide, such as longer windows or switching to a fallback model after repeated 529s.

Where a gateway fits

byesu is an AI API gateway with OpenAI-compatible (/v1/chat/completions) and Anthropic-native (/v1/messages) endpoints, billed pay-as-you-go with no subscription. Two properties change the 429/529 picture:

• Multi-channel routing. The gateway maintains multiple upstream channels per model. When one upstream returns a 529, routing can retry the request on another channel before the error ever reaches your client — many overload incidents simply disappear into a slightly slower response.
• One key, many models. The same sk- token covers Claude, GPT-5.6, Grok, and Gemini. A model-level fallback after repeated 529s — say, claude-sonnet-5 → gpt-5.6-sol — is a one-string change inside your existing retry handler, with no second account or SDK swap.

Errors pass through in the format your client expects (OpenAI-compatible or Anthropic-native), so the retry code above keeps working unchanged. If you see a "no available channel" error instead, that is a token-group issue, not a rate limit — see Choosing a Group.

Related links

• Quick Start (3 steps) — create a token · set the address · pick a model
• Common Errors — the full error troubleshooting index
• Console Sign-up / Create Token — get an sk- token and see live pricing

FAQ

What is the difference between Claude API 429 and 529 errors?

A 429 rate_limit_error means your key or organization exceeded a quota such as requests per minute or tokens per minute — you are being throttled. A 529 overloaded_error means the upstream service is temporarily out of capacity — your quota is fine. Both are retryable, but 429 comes with a retry-after header telling you exactly how long to wait, while 529 needs exponential backoff with jitter.

Should I retry a 429 rate_limit_error immediately?

No. A 429 is deterministic: retrying immediately consumes more of the same quota and keeps you throttled. Read the retry-after response header, sleep for that many seconds, then retry. If 429s are frequent, add client-side throttling or a request queue rather than more retries.

How long should I wait after a 529 overloaded_error?

There is usually no retry-after header on a 529, so use exponential backoff with jitter: wait roughly 1–2 seconds on the first retry and double the delay on each attempt, capping around 30–60 seconds. Overload episodes are typically short, so a handful of spaced retries resolves most of them.

Does the Anthropic SDK retry 429 and 529 automatically?

Yes. The official Anthropic SDKs automatically retry 429 and 5xx-class errors (including 529) with exponential backoff, honoring the retry-after header when present. The default is 2 retries, configurable via max_retries. Add your own retry loop only when you need behavior beyond that, such as longer backoff windows or fallback to another model.

Why am I getting 429 errors while sending very few requests?

Rate limits count tokens as well as requests. A few requests with very large prompts or a high max_tokens can exhaust the input- or output-token bucket long before the request-count bucket. Check the anthropic-ratelimit-input-tokens-remaining and anthropic-ratelimit-output-tokens-remaining headers, trim prompts, and lower max_tokens where possible. A key shared across several services can also burn the quota invisibly.

How does an AI API gateway help with 429 and 529 errors?

A gateway like byesu pools capacity across multiple upstream channels. When one upstream returns a 529, routing can retry the request on another channel automatically, so many overload incidents never reach your client. One key also covers Claude, GPT-5.6, Grok and Gemini, which makes a model-level fallback a one-string change in your retry handler.