Key takeaways
- Not every 429 is a rate limit. On the Claude API, a 429 with error_code enforced_spend_limit_reached means the monthly spend cap was hit, and it carries no retry-after header, so retries fail until 00:00 UTC on the 1st of the next month.
- Branch on the response, not the status code: a rate-limit 429 carries retry-after in seconds, a spend cap you set yourself returns 400, and the tier spend cap returns 429 without a wait time.
- The Claude API meters three limits per model class: requests, input tokens and output tokens per minute. Sonnet 5.5 on the Start tier allows 1,000 RPM, 2,000,000 ITPM and 400,000 OTPM.
- A limit of 60 requests per minute may be enforced as 1 per second, so a fleet that fires 20 sub-agents at once can be rate limited well under its per-minute ceiling.
- Cached reads do not count toward input tokens per minute on most Claude models. Anthropic's example: a 2M ITPM limit with an 80% cache hit rate processes 10M input tokens a minute.
Not every 429 from the Claude API means “slow down”. Anthropic’s rate limits documentation, read on 13 October 2026, describes a 429 that carries no wait time at all: the monthly spend cap, which holds until 00:00 UTC on the first day of the next month.
An agent loop that treats every 429 the same way will keep retrying that one forever. Before the run decides to wait, it has to know which limit fired.
Which 429 did the run actually get?
Three different conditions reach an agent as “rate limited”, and only one of them clears by waiting a few seconds.
| Condition | HTTP status | Wait time in response | Clears on its own | Loop action |
|---|---|---|---|---|
| Rate limit (RPM, ITPM or OTPM) | 429 | retry-after, in seconds | Yes, as the bucket refills | Wait the stated time, then retry |
| Acceleration limit after a sharp usage rise | 429 | Check the response | Yes, with a gradual ramp | Lower fleet concurrency, ramp back up |
| Tier monthly spend cap | 429 | None | No, until 00:00 UTC on the 1st | Stop retrying, park the run, page a human |
| Spend limit you set yourself | 400 | Message states when access resumes | No, until reset or raised | Same as above |
The spend-cap 429 is the dangerous one, because it looks like an ordinary rate limit. Anthropic’s documentation gives it the same error type, rate_limit_error, and tells you to read error.details.error_code to tell them apart. The value is enforced_spend_limit_reached. Retrying, including an SDK’s automatic retries, fails until access resumes.
The tier caps are $500 a month on Start, $1,000 on Build and $200,000 on Scale. A team on the Build tier running a fleet of agents can reach $1,000 in an afternoon, and from that moment every run in the organisation stops at once.
Why does exponential backoff alone not fix it?
Because backoff spaces out one caller, and an agent run is many callers drawing on one bucket.
The Claude API uses a token bucket, so capacity refills continuously rather than resetting on the minute. It also enforces limits over intervals shorter than a minute. Anthropic’s example is a 60 requests-per-minute limit enforced as 1 request per second. A planner that fans out 20 sub-agents in the same second can be refused while the minute’s total is nowhere near the ceiling.
Each sub-agent then backs off on its own schedule. If they share a backoff policy and started together, they also tend to wake together. The second wave hits the same refilled bucket at the same moment, and the run spends its time in synchronized retries. Jitter helps. A shared limiter that knows the bucket’s state helps more.
The official Anthropic SDK already retries rate limits twice by default and honours retry-after when it is present, according to the Claude API errors documentation. That is correct for a single caller. In a fleet, those 2 retries per sub-agent are 40 extra requests from 20 sub-agents, all aimed at the bucket that just refused them. A 529 overloaded_error is a different signal again: it reports load across all users, not your organisation’s limit.
Every retry also resends the full context. A retry is not one more small request; it is another full input bill and another draw on input tokens per minute, which is why a run-level token budget has to count retries, not just successful turns.
What should the orchestrator do with retry-after?
Use it, and make it the run’s clock rather than each agent’s.
Anthropic returns retry-after as the number of seconds to wait, and states that earlier retries will fail. The response also carries anthropic-ratelimit-* headers for requests, input tokens and output tokens: the limit, what remains, and the reset time in RFC 3339 format. Token counts in those headers are rounded to the nearest thousand.
That is enough to build one limiter for the whole run:
- Read the headers on every response, not only on errors. The remaining counts tell the orchestrator how close the run is to the limit before it hits it.
- On a rate-limit 429, pause dispatch for the whole run for the retry-after interval, plus jitter. Do not let sub-agents keep sending while one of them waits.
- Resume at reduced concurrency. If the run hit the limit at 20 parallel agents, it will hit it again at 20.
- Treat repeated 429s as an acceleration signal. Anthropic notes that a sharp increase in usage can trigger acceleration limits, and recommends ramping traffic gradually.
A rate limit is the one error class that the retry, repair or escalate table sends to “retry with longer backoff”. The point here is narrower: longer backoff only works when the run, not the agent, owns the wait.
Can caching raise the ceiling instead of waiting?
Often, yes, and it is the cheapest change in this article.
On most current Claude models, only uncached input tokens and cache writes count toward input tokens per minute. Cache reads do not. Anthropic’s own example: with a 2,000,000 ITPM limit and an 80% cache hit rate, an organisation can process 10,000,000 input tokens a minute, because the 8,000,000 cached tokens are not counted.
Agent runs resend the same system prompt, tool definitions and early history on every turn, which is exactly the material a cache absorbs. If your 429s come from input tokens rather than requests, check your cache hit rate first. Prefix ordering mistakes that silently break the cache will show up here as rate limits, not as a cost line.
Output tokens behave differently. Anthropic evaluates output tokens per minute against tokens actually generated, and max_tokens does not count toward it, so lowering max_tokens will not relieve an output-token 429.
| Tier | Requests per minute | Input tokens per minute | Output tokens per minute | Monthly spend cap |
|---|---|---|---|---|
| Start | 1,000 | 2,000,000 | 400,000 | $500 |
| Build | 5,000 | 5,000,000 | 1,000,000 | $1,000 |
| Scale | 10,000 | 10,000,000 | 2,000,000 | $200,000 |
What should a run do when the 429 is the spend cap?
Stop spending effort on it. The Claude API’s spend-cap 429 will not clear within the run’s lifetime.
The useful behaviour is to park, not to fail. Checkpoint the run’s state, mark it as blocked on the spend cap, and raise one alert for the organisation rather than one per run. When the limit is raised or the month turns, the parked runs can resume from their checkpoints. This is the same degrade-gracefully behaviour that a fleet needs when a provider rations capacity, triggered by your own account rather than the provider’s.
Anthropic also documents a separate case: Claude Code requests over the Claude Code workspace’s limit can receive a 429 that does carry retry-after. The header, not the status code, is what tells the loop whether waiting will help.
The check that belongs in every agent loop is short: on a 429, read retry-after; if it is missing, read the error code before retrying anything.
Frequently asked questions
Why does my AI agent keep getting 429 errors even with exponential backoff?
Because backoff spaces out one caller, not the fleet. If every agent in a run backs off independently and then resumes together, they hit the same token bucket again at the same moment. Use the retry-after value and a shared limiter.
How long should I wait after a 429 from the Claude API?
As long as the retry-after header says, in seconds. Earlier retries will fail by design. If the 429 has no retry-after header, check error.details.error_code before waiting at all.
What does enforced_spend_limit_reached mean?
It means the organisation reached the monthly spend cap for its usage tier. API usage pauses until 00:00 UTC on the first day of the next month unless the limit is raised, so automatic retries cannot succeed.
Do cached tokens count toward Claude rate limits?
Not on most current models. Only uncached input tokens and cache writes count toward input tokens per minute; cache reads do not. Claude Haiku 3.5 is the documented exception.
Does a high max_tokens value use up my output rate limit?
No. Anthropic evaluates output tokens per minute in real time against tokens actually generated, and the max_tokens parameter does not factor into it.
Method and sources
- Anthropic, Rate limits, Claude API documentation, read 13 October 2026. Source of the RPM, ITPM and OTPM limits per tier, the token bucket description, the 60 RPM enforced as 1 per second example, the retry-after and anthropic-ratelimit-* headers, the spend caps of $500, $1,000 and $200,000, the enforced_spend_limit_reached error code, the 400 response for user-set limits, cache-aware ITPM and the 2M ITPM with 80% cache hit example.
- Anthropic, Errors, Claude API documentation. Source of the rate_limit_error and invalid_request_error types, the 529 overloaded_error, and the official SDK's default of 2 automatic retries that honour retry-after when present.
- The run-level policy in the last two sections, including the order of checks and the decision to park a run rather than fail it, is our editorial judgement. We ran no load test of our own and publish no throughput figures of our own.