Claude Code "API Error: Rate limit reached": the 429 and the fix
A 429 from the Claude API, printed by Claude Code. Below: what Anthropic’s docs say it is, the one header that tells you how long to wait, and a key where the limits are yours.
What the client prints
API Error: Rate limit reached # The body behind that line, in the Claude API's error shape:{ "type": "error", "error": { "type": "rate_limit_error", "message": "..." }, "request_id": "req_..."}What it means
Anthropic's API errors page (read 2026-10-31) defines 429 rate_limit_error as: 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.
The rate limits page (same date) measures limits per model class in requests per minute, input tokens per minute and output tokens per minute, per organization, with a token bucket: a 60-requests-a-minute limit can be enforced as one request a second, so a burst trips it. Claude Code sends the conversation and file context on every turn, so a long session meets the input-token limit first. Cached reads do not count toward it on most models.
One 429 is not a rate limit at all: the tier spend cap. The same page says that response carries no retry-after and keeps failing until 00:00 UTC on the first of the next month, with error.details.error_code set to enforced_spend_limit_reached.
The retry rule
When the response has a retry-after header, wait that many seconds before retrying (Anthropic's rate limits page, 2026-10-31). Earlier retries fail. Claude Code and the official SDK retry transient errors with exponential backoff and honour the header when it is present.
No retry-after and a message about the monthly usage threshold means the spend cap: stop retrying, the clock is the calendar.
A limit you hit every afternoon is a budget problem, not a backoff problem. The fix below moves the session to a key with its own limits.
A key that fails over, with limits you set
A retry loop treats the symptom. On this key the next route is tried before the error reaches you, every limit is per key, and a failed request costs nothing. From the OpenAPI document, read 2026-10-31.
- Failover before you see it
- A route that fails with a 5xx or a 429 is retried on the next route for the same model. x-uplink-attempts on the answer counts the tries; the price is the model’s own either way.
- Your own fallback list
- models: [...] names up to 5 models tried in order once every route of the one before has failed before a byte was sent. Each bills at its own price when it answers.
- Failed requests are not charged
- A 429, 502 or 503 from this API charges nothing and carries retry-after: back off that long before trying again.
- Limits per key, set by you
- rpm from 1 to 100,000, tpm from 1 to 50,000,000 and concurrency from 1 to 10,000 on each key. Default: 600 requests a minute per key, 50 in flight per account.
- A budget per key
- budget_usd plus a daily, weekly or monthly spend limit. The key stops at its own line with a 402; the rest of the balance is untouched.
- One request id
- x-uplink-request-id on every answer, errors included. Quote it and we find the call.
Claude route, right now
From GET https://api.relayswitch.io/v1/status, the public feed behind /status, generated 2026-11-02T06:27:18.378Z.
| Service | State | Last check | Latency | Checks today | Failures today |
|---|---|---|---|---|---|
| Claude | Operational | Nov 2, 2026, 6:07 AM UTC | — | 7 | 0 |
Every hour the gateway counts the past hour’s real requests to this route: answered or failed. A request answered after a retry counts as answered.
The daily real-model check: 305 of 339 models answered as before, generated 2026-11-02T06:27:18.383Z. Every verdict is on /proof.
The ids this page is about, per million tokens
The Claude ids Claude Code can run on this key, in the Anthropic Messages format it expects.
| Model | Input | Output | Developer list in / out |
|---|---|---|---|
| Claude Opus 5.5claude-opus-5-5 | $2.80 | $10.00 | $4.00 / $20.00 |
| Claude Sonnet 5.5claude-sonnet-5-5 | $1.20 | $3.00 | $2.00 / $10.00 |
| Claude Haiku 5.5claude-haiku-5-5 | $0.06 | $0.15 | $0.10 / $0.50 |
Read from the catalog at render. A request that fails over bills at the price of the model that answered.
Two variables and Claude Code runs here
export ANTHROPIC_BASE_URL="https://api.relayswitch.io/v1"export ANTHROPIC_AUTH_TOKEN="sk-relay-..."claudeClaude Code's environment variables reference (read 2026-10-31) lists ANTHROPIC_BASE_URL as the way to route requests through a proxy or gateway and ANTHROPIC_AUTH_TOKEN as the value of the Authorization header. Nothing else changes: same tool, same model ids, same Messages format.
The Claude Code setup guide has the settings.json form, a key for Claude Code alone with a budget, and the check that the request landed.
Questions
From what people ask about this error.
A key that does not stop at one host
Failover at the same price, limits and a budget per key, failed requests not charged. Card or crypto, no KYC, no subscription.