Your Bot Just Got a 429 From Claude. Is It a Rate Limit or a Spend Cap?
Anthropic's Claude API returns HTTP 429 for two unrelated problems: a per-minute rate limit and a monthly spend cap. They look identical in the status code but require opposite fixes. A bot that retries on both will loop forever against one of them.
AI-assisted editorial: researched and drafted with AI using the primary sources linked below. Examples are illustrative; they are not measured product results. Editorial policy.
Key takeaways
- A 429 with a retry-after header is a per-minute rate limit; back off and retry. A 429 without one is usually the monthly spend cap, and retrying cannot succeed.
- The spend cap pauses the whole organization until the next calendar month unless Anthropic raises the tier, so a single runaway bot can take down every other bot sharing that API key's organization.
- Check the retry-after header before you retry, and set your own spend limit below your tier's cap so you get a controllable stop instead of a surprise one.
Two limits, one status code
Anthropic's Claude API enforces two kinds of limits on an organization, and both can surface as the same HTTP 429. The first is a rate limit: a ceiling on how many requests, input tokens, or output tokens an organization can send in a given period. The second is a spend limit: a ceiling on how many dollars an organization can spend on the API in a calendar month.
These are not variations on a theme. A rate limit clears itself in seconds or minutes once traffic slows down. A spend limit does not clear until the calendar turns over, no matter how quiet your bot goes. If your retry logic treats every 429 the same way, it will handle one of these correctly and loop uselessly against the other.
Each standard usage tier carries its own spend ceiling: the Start tier caps monthly spend at $500, Build at $1,000, and Scale at $200,000, with the Custom tier carrying no fixed cap because its limits are arranged directly with Anthropic's account team.
Sources: Rate limits - Claude Platform Docs.
The one header that tells you which wall you hit
Anthropic's documentation describes a retry-after response header that tells a client how many seconds to wait before trying again, warning that earlier retries will fail. Critically, the documentation also states that this header is not present on every 429, and specifically that the spend-cap 429 never carries it.
That gives you a reliable discriminator without parsing error bodies or guessing from context. If retry-after is present, you are looking at a per-minute rate limit: requests, input tokens, or output tokens per minute. Wait the stated number of seconds and retry; the limit is designed to clear. If retry-after is absent, do not retry on a timer. You have hit something that a delay cannot fix.
This matters because standard retry middleware, including the kind built into many SDKs, treats a 429 as transient by default. Against a rate limit that assumption is correct. Against a spend cap it produces a tight loop of failed requests that burns through whatever request budget remains and tells you nothing new on each attempt.
Sources: Rate limits - Claude Platform Docs.
Worked example: a nightly digest bot that outlives its budget
Say a small team runs a bot that summarizes support tickets every night, calling Claude once per ticket. Volume is steady for three weeks, then a product launch triples ticket count for four days straight. The organization is on the Build tier.
On night two of the spike, the bot's calls start failing. The error is a 429, same as always. If the on-call engineer assumes it's the familiar per-minute rate limit, they will restart the job, watch it fail again immediately, and conclude something is broken in the retry logic. It isn't. The organization's cumulative spend for the month crossed the Build tier's $1,000 cap partway through the run, and every call in the organization, not just this bot's, is now refused until the calendar turns over or someone requests a higher limit.
The fix is not a longer backoff. It is checking for the retry-after header on that specific failure. Its absence is the signal that this is the spend cap, at which point the available actions are: request a tier increase from Anthropic, wait for the next billing month, or stop sending non-essential calls from other bots sharing the same organization so whatever budget remains goes to higher-priority work.
Sources: Rate limits - Claude Platform Docs.
What to build before this happens to you
Set your own spend limit below your tier's cap, rather than letting the tier cap be the first alarm you ever see. Anthropic's spend limit controls let an organization configure a cap scoped below the one Anthropic sets from the usage tier, which gives you a controllable stop instead of an unannounced one that also blocks every other bot in the same organization.
In code, branch on the presence of retry-after rather than on the bare fact of a 429. Treat its presence as a short, bounded wait-and-retry. Treat its absence as a hard stop: alert a human, do not retry on a schedule, and surface which organization or workspace is responsible so the right person can act.
If more than one bot shares an API key's organization, that shared spend cap is a shared failure domain. A single misbehaving bot can silently stop every other bot's Claude calls for the rest of the month. Scoping spend limits per workspace, where your account structure supports it, keeps one routine's overspend from taking down the others. BotBento is building run-level cost tracking so a team can see which routine is approaching a shared cap before it fires, rather than after.
Sources: Rate limits - Claude Platform Docs, Spend Limits - Claude API Reference.
Primary sources
Sources checked 2026-10-20. Standards and product documentation can change; follow the linked version when implementing.
- Rate limits - Claude Platform Docs — Anthropic
- Spend Limits - Claude API Reference — Anthropic
BotBento is in development. Suggest a correction.