Fix Claude Code 429 "Rate Limit Exceeded": Complete Triage Guide

The Error Message That Stops Your Work Cold

You are thirty minutes into a complex refactor. Claude Code has just finished reading seventeen files and started writing the new implementation. Then the session freezes, and you see one of these:

• Error: 429 Too Many Requests
• Error: rate_limit_exceeded — Please reduce the rate of your requests
• Error: Your organization has been rate limited
• The service is temporarily unavailable. Please try again in a few minutes

If you are paying $20, $100, or even $200 per month for a Claude plan, this feels unfair. You paid — why are you being throttled?

This guide is a practical triage: diagnose your exact 429, fix it in 60 seconds if possible, and understand what tools exist to stop it from happening again.

60-Second Triage

Before anything else, run through this check:

1. Check the CLI output for a retry-after value. If it says "retry after 15 seconds," wait those seconds — the error is transient.
2. Look at the exact error type in the response:
   • rate_limit_exceeded — you hit a request or token per minute cap
   • overloaded_error — the upstream API is at capacity (not your fault)
   • tier_limit or usage_limit — you hit a daily or monthly plan cap
   • invalid_api_key / authentication_error — not actually rate limit, it is an auth problem misreported
3. Check the time. If it is peak US working hours, traffic is heavier and lower-priority requests get throttled first.

If the error persists after one retry, continue reading.

The Three Types of 429 in Claude Code

Not all 429s are the same. The fix depends entirely on which one you have.

Type 1: rate_limit_exceeded — Your Per-Minute Cap

This is the most common 429. Claude Code burns tokens fast: a single message that includes a 50 KB file already chews up 12,500 tokens of input. Many API tiers permit only 40,000 input tokens per minute.

How to confirm:

claude --verbose 2>&1 | grep -i 'x-ratelimit'

Look for:

x-ratelimit-limit-tokens: 40000
x-ratelimit-remaining-tokens: 0
x-ratelimit-reset-tokens: 2026-04-23T14:32:00Z

If remaining-tokens is at or near zero, this is your error.

What to do: Wait until the reset timestamp (usually 30-60 seconds). Then resume. If this happens every few minutes, your tier is too low for the work you are doing — see the section on alternative backends below.

Type 2: overloaded_error — Upstream Capacity Issue

This one is not your fault. When the upstream API has high load, it sheds traffic starting with lower-tier customers. You will see:

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "The service is temporarily unavailable"
  }
}

What to do:

• Retry in 30-60 seconds. If it still fails, wait 5 minutes.
• Check the provider's status page — if there is an active incident, your only option is to wait or switch backends.
• If this happens more than twice per session, your backend is not providing the availability you need for serious work.

Type 3: tier_limit — You Hit a Plan Cap

If you are on a plan with invisible daily usage caps, you will eventually see messages like "You've reached your usage limit for today" — this is a 429 in disguise.

What to do: You cannot work around this on the same account. You either wait until the cycle resets (usually midnight in the billing time zone), upgrade to a higher tier, or switch to a backend with different cap structure.

How to Read Claude Code Rate Limit Headers Properly

Most Anthropic-compatible APIs expose five relevant headers on every response:

Header	Meaning
x-ratelimit-limit-requests	Requests allowed per minute
x-ratelimit-remaining-requests	Requests left in the current window
x-ratelimit-limit-tokens	Input tokens allowed per minute
x-ratelimit-remaining-tokens	Tokens left in the current window
retry-after	Seconds to wait before retrying (sent only on 429)

If you capture responses manually with curl:

curl -i $ANTHROPIC_BASE_URL/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5","max_tokens":100,"messages":[{"role":"user","content":"hi"}]}'

Look at the x-ratelimit-remaining-tokens header. If it is below 10,000 and you are about to send a big file, you will 429.

The Retry Loop Problem

Claude Code CLI has built-in retry logic with exponential backoff. This sounds great until you realize:

1. Each retry still consumes your rate budget
2. If the server is genuinely overloaded, retries pile up
3. Your session hangs for two to five minutes while retries fail silently

You cannot fix retry behavior from the CLI. If you are seeing retry stacks regularly, the underlying tier or backend is not adequate. Upgrading retries does not fix the source.

Short-Term Workarounds That Actually Work

If you need to ship something today and cannot switch backends:

1. Throttle your own prompts. Pause 5 seconds between messages. Crude, but it prevents burst-related 429s.

2. Compact the context. Use /compact in Claude Code between major tasks. Shorter context means fewer tokens per request means less rate pressure.

3. Split your work. If you are refactoring ten files, do three, wait 2 minutes, do three more. This respects the per-minute window.

4. Avoid peak hours. If you can, schedule heavy sessions before 8 AM or after 7 PM US time. The difference in 429 frequency is dramatic — some users report zero errors off-peak versus every 20 minutes during peak.

None of these are actual fixes. They are coping mechanisms.

The Structural Fix: A Multi-Provider Relay

Claude Code CLI is configurable via the ANTHROPIC_BASE_URL environment variable — this is officially documented behavior. You can point it at any API that speaks the Anthropic API protocol.

One option is a multi-provider relay service like LLM API. A relay offers:

• Multi-upstream routing — your traffic can flow through multiple compatible API providers, so a single provider's per-minute cap does not stall your session
• Automatic failover — when one upstream has a capacity incident, traffic shifts to a healthy one
• Unified billing — one key, one dashboard, one invoice across providers
• Regional accessibility — endpoints hosted in regions where direct access to some providers is unreliable

Setup takes 60 seconds:

export ANTHROPIC_BASE_URL=https://llmapi.pro
export ANTHROPIC_API_KEY=your-llmapi-key
claude

Claude Code CLI does not need to know it is talking to a relay — it sees an API endpoint that conforms to the Anthropic protocol.

FAQ: Common 429 Questions

Does adding more retries help? No. Claude Code already retries internally. Adding more retries just delays the eventual failure.

Will rotating my API key fix this? No. Rate limits are per-organization, not per-key. Rotating keys does nothing.

Does using multiple accounts work? Most providers prohibit this in their terms of service and detect duplicates through payment method fingerprinting. Not worth the risk for the small savings.

Why does claude --model claude-haiku-4-5 not 429 as often? Haiku has higher rate limits because its tokens are cheaper. If your task is lightweight, Haiku is a legitimate workaround.

Can I buy a higher tier directly from the provider? Yes — most providers offer tiered limits, but reaching the top tier usually requires sustained high spend. Most individual developers never qualify.

Bottom Line

A 429 in Claude Code is not user error. It is an infrastructure limit imposed by your backend for their benefit, not yours. You can cope with workarounds, or you can use a different backend structure — a multi-provider relay like LLM API — that routes around single-provider caps.

Set two environment variables, keep using Claude Code exactly as before, and reduce 429 events to near-zero.

Try LLM API →