← Insights

Claude 429 Errors: What They Mean and How to Fix Them

A 429 error means a request hit a limit, not that Claude is down. The error and headers show how long to wait, which quota applies, or whom to contact.

12 min read
Claude 429 Errors: What They Mean and How to Fix Them

A 429 error means your request triggered a limit. It does not mean Claude is down. Read the error message and the response headers first: they show how long to wait, which quota you hit, or whether to contact your provider or gateway.

Tigerless Labs’ cost-xray shows which parts of each Claude Code request use input tokens. Use it to investigate input-token limits. The cost-xray product page describes a local capture proxy for Claude Code and Codex. Capture is automatic when you run claude or codex as before, with no flags and no base-URL change. It attributes each request's tokens and cost to its sources: the system prompt, tool schemas, MCP servers, messages, cache activity and tool results. When the error points at input tokens per minute, that breakdown shows which source is large.

I'm encountering 429 errors, and I'm worried my rate limit is too low. What should I do?

Start from the message, not from your settings. Find the code or the phrase in the error, then take the action in its row of the table. Each section below explains one of these messages: its signal, its scope and its fix.

What you seeWhat to do
A 429 with a retry-after headerWait that many seconds, then retry.
ramp_limit_exceeded in the error detailsYour usage rose too fast. Wait, then send at a rate that succeeds and raise it one step at a time.
enforced_spend_limit_reached in the error details, with no retry-after headerYour organization reached its tier's monthly spend cap. Wait for the reset, or move to a higher tier.
HTTP 400 whose message starts with You have reached your specified API usage limitsYou set a spend limit yourself, and it was reached. Raise or remove it.
API Error: Request rejected (429) in Claude CodeRun /status to see which credential is in use, then check the limit of the service the message names.
API Error: Server is temporarily limiting requests (not your usage limit)A short server throttle. Wait briefly and send again.
You've hit your session limit, or a weekly or model limitYour plan's window is used up. Wait for the reset time in the message.

Rate limits are measured per model class in three units: requests per minute, input tokens per minute and output tokens per minute. Exceed any one of them and the 429 names the limit you passed. Limits also hold over short windows, so 60 requests per minute can be enforced as one request per second, and a short burst can fail even when the minute total looks fine.

The error body carries the code, and the headers carry any wait time. Note both before you change anything, because the same status code can come from several different limits.

How do I tell a rate limit from a spend cap?

Read the response, not only the status code. A rate limit 429 can carry a retry-after header with the number of seconds to wait. Wait that long, then retry. Every response also carries a request ID, in the request-id header and the request_id field of the error body. Keep it, because support needs it to find the request.

A spend cap is set by the tier. The Start, Build and Scale tiers each carry a monthly spend cap. Organizations on the Custom tier have no monthly spend cap, and their limits are arranged with their account team. The API places an organization on a tier automatically, based on its usage history and account standing. New organizations, and organizations with limited usage history, may start on the Evaluation tier, with limits below the standard ones. Those limits rise automatically as usage history builds. The cap amounts are on the rate limits page.

When an organization reaches its tier's cap, the response is an HTTP 429 with the error code enforced_spend_limit_reached. It has no retry-after header:

{
  "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"
}

Retries fail, including the SDK's automatic retries, until API usage resumes at 00:00 UTC on the first day of the next month. Moving to a higher tier restores access sooner. The error type is the same rate_limit_error that an ordinary rate limit uses, so read error_code before you decide how long to wait.

A spend limit you set yourself is a separate case. You can set it below your tier's cap in the Console. When it is reached, the API returns HTTP 400 with an invalid_request_error, not a 429. The message starts with You have reached your specified API usage limits, or with You have reached your specified workspace API usage limits for a workspace limit. Raise or remove the limit to restore access sooner. A 400 with a different message points to a problem in the request itself, and changing a spend limit will not help with it.

Claude Code workspace limits are checked separately. A request over that workspace's limit can receive a 429 that carries a retry-after header, so the wait rule above applies. Organization-wide limits always apply, even when workspace limits add up to more.

Why do I get a 429 when I'm under my limit?

The signal is the error code ramp_limit_exceeded in the error details, after a script, a batch job or another client has suddenly sent far more requests than it did the day before. A ramp limit caps how fast your organization's token usage on a model can grow. A 429 can arrive while your per-minute totals still look fine, and a burst of requests within a few seconds can count as a sharp increase too.

The ramp limit follows your recent use. It is your organization's highest per-minute usage of the model in the recent past, plus a step, so each minute you can go up to one step above that peak. It stops rising at your rate limit. After a period of lower usage it comes back down, but it never drops below a starting amount. It applies to the Messages API and to any model, and fast mode has its own ramp limits.

The per-minute limits work differently from the ramp limit. The API uses a token bucket: capacity refills continuously up to your maximum, rather than resetting at fixed intervals. A short pause after a burst therefore recovers some of the capacity.

The fix has three steps. First, wait at least the number of seconds in the retry-after header. Second, hold traffic at a level where requests succeed. Third, raise it by at most one step per minute. Start scheduled or bulk jobs at a low rate, and spread requests evenly rather than sending everything at once. The error message usually states the current ramp limit, the step and your rate limit. Read those numbers before you change the schedule, because they show how far above the ramp your traffic is.

The Message Batches API is not subject to ramp limits. A job that can wait for its results can use it instead of the Messages API.

Why does my input-token limit run out when my request count looks normal?

Input tokens are counted differently from requests, and cache use changes the count. The input tokens per minute limit counts input_tokens and cache_creation_input_tokens. Tokens read from the cache, cache_read_input_tokens, do not count toward that limit. The total input of a request is the sum of the three fields. Input tokens and output tokens are counted separately, so a long answer can use up the output limit while the input limit still has room. The API reports only the part after the last cache breakpoint as input_tokens, so a request with a cached 200,000-token document and a 50-token question shows input_tokens of 50, even though the request holds 200,050 input tokens. A coding agent resends the same long prefix on every turn, so most of that prefix can come from the cache and use less of the limit. Tokens read from the cache do not count toward the ramp limit either.

To find the large part, open cost-xray's live view with cx. It drills from the top down: agent, project, session, category, MCP server, tool, per-turn call, and then the real output. Its totals show tokens and cost for each source. Look for the part that repeats on every turn: a long system prompt, a tool schema for an MCP server the task does not use, or tool results that keep growing as the session runs.

Act on the largest part. Remove the MCP servers and plugins the task does not need, since each plugin that adds tools also adds schemas to every request. Open-Source Claude Code Plugins Worth Installing lists some options. Start a new session when the history has grown long. How to Give Claude Code Memory Across Sessions covers one way to keep each session's history short, and Tigerless Labs Agent Memory takes up the same question from the Labs side. To see the price of each part of a request, read See What Claude Code Sends to the API and What It Costs. The Cost X-Ray launch post explains how the capture works.

What does a 429 mean in Claude Code when I use a subscription or a gateway?

Claude Code shows API Error: Request rejected (429) when the rate limit configured for the credential in use has been hit. That credential can be an API key, an Amazon Bedrock project or a Google Cloud project. The sentence after the · names where to check service health: the Anthropic status page, or the status page of the provider in use. With a custom ANTHROPIC_BASE_URL, it names the gateway host. When a proxy or load balancer answers with its own HTML 429 page, the text after the · is that page's title, such as Too Many Requests. In that case the proxy is the one that returned the error, so its operator's logs are where to look.

Start with /status, which shows the credential Claude Code is using. An ANTHROPIC_API_KEY in your environment is used instead of your Pro, Max, Ultra, Team or Enterprise subscription, even when you are logged in. In interactive mode Claude Code asks you to approve the key once. If you meant to use your subscription, run unset ANTHROPIC_API_KEY. A key you did not expect can send requests to a lower limit than your subscription has.

Then check the limit of the service the message names. For an Anthropic API key, that is the rate limits page in the Claude Console, which shows the tier and per-workspace caps. For a gateway, ask the operator before you change your own settings. The rate limits page also covers Claude Platform on AWS, where billing runs through AWS Marketplace, new organizations start on the Start tier, and per-workspace rate limit configuration is not available.

Plan and gateway messages have their own wording. You've hit your session limit · resets 3:45pm means your subscription's window is used up, and access returns at the time shown. Switching models does not restore it, because the session and weekly limits are shared across all models. A lowercase spend limit reached · resets Dec 1 that you see through a Claude apps gateway is the gateway operator's cap, not your plan's.

The server throttle is different. API Error: Server is temporarily limiting requests (not your usage limit) means the server is throttling briefly. Claude Code can tell it apart from a plan limit, because a real plan limit comes with quota headers that this response lacks. On v2.1.199 and later, Claude Code retries it automatically with backoff before it shows the error.

If the limit belongs to your provider or gateway, reduce the load you send to it: avoid running many parallel subagents, or switch to a smaller model with /model for high-volume scripted runs. If you also work in Codex, Can a Codex Skill Run in Claude Code? What Carries Over explains what moves between the two tools.

When is waiting not the fix?

Waiting fixes a rate limit, a ramp limit you ease off, and a short server throttle. It does not fix a spend cap. Retries fail until the cap resets or the tier rises. Claude Code retries transient failures up to 10 times with exponential backoff before it shows an error. It retries a server error or an overloaded response that arrives before any text has streamed, and it re-issues a dropped connection. It does not always retry a failure that arrives partway through a response. A server error or overloaded response that arrives after Claude has finished thinking, but before any text or tool call starts, is retried up to two times. Pressing send again over and over only adds requests to the same throttle. If a throttle lasts a long stretch, check status.claude.com.

Unattended jobs such as CI need a different setting. Setting CLAUDE_CODE_RETRY_WATCHDOG to 1 makes Claude Code retry 429 and 529 capacity errors indefinitely, instead of failing after CLAUDE_CODE_MAX_RETRIES attempts. Its backoff runs up to 5 minutes between attempts, or until the limit resets when the response carries a reset time. It does not wait out a spend limit. Claude Code fails at once when a standard-speed request gets a 429 that reports a spend limit or exhausted usage credits, even one from a gateway spend cap that resets on a schedule.

Switching to a smaller model helps when the request volume on one key is the trouble. It does nothing for an organization that has used up its monthly cap. For Codex, Codex Effort: What It Changes and Which Level to Pick explains what each effort level changes. Plan limits also differ between tools. Codex vs Claude Code sets out how each vendor meters its plan limits alongside the score and the cost per task.

Conclusion

The fix is the one that matches the message's own words. A retry-after header means wait that long. ramp_limit_exceeded means ramp up from a rate that succeeds. enforced_spend_limit_reached means wait for the reset or move to a higher tier. A 400 that starts with You have reached your specified API usage limits means raise your own spend limit. Request rejected (429) means check /status and the limit of the service the message names. A plan message means wait for its reset time.

The rule that decides most cases: if the message gives a time when access returns, wait for that time. If it names a limit someone set, the party that set it changes it, whether that is you, your provider or your gateway operator. If neither applies, find the largest source of tokens with cost-xray before you cut anything.

Your next step is to read the error's code and headers, then take the action in its row of the table above.

FAQ

Does a 429 error mean Claude is down?

No. A 429 means the request reached the server and was refused because a limit applied to it. An outage usually shows up as a different error, such as a 529 overloaded error, which means the API is temporarily overloaded. The status page of the affected service says how far an outage reaches; for Claude, see status.claude.com.

Should I retry a 429 right away?

Not every time. If the 429 has a retry-after header, wait that many seconds first. If it carries the code enforced_spend_limit_reached, retries fail until access resumes. The official SDKs retry transient errors, including rate limits, twice by default and honor the retry-after header when it is present.

Can I ask for higher rate limits?

Yes. Use Request tier increase on the Rate limits page in the Claude Console. Organizations on the Custom tier arrange their limits with their account team.

Do cached tokens count toward the input rate limit?

Cache reads do not count toward the input tokens per minute limit. Uncached input tokens and cache writes do.

Can I see which part of a request uses the tokens?

Yes. cost-xray, a Tigerless Labs tool, captures Claude Code and Codex traffic on your machine and attributes tokens and cost to each source, such as the system prompt, tool schemas, MCP servers and tool results.

Share this article

Keep reading

11 min read

Should Agent Memory Have an Expiration Date?

A fixed expiry can drop facts that are still true. Here is how TTL, decay and event-based expiry differ, and when a fact should stay valid until replaced.

Read story