Your retry loop will never clear this 429

// one status code, three conditions

The errors page lists what a 429 can mean, and only the first item is what most handlers assume:

Three conditions, one HTTP status, one error.type. The field every retry handler branches on is identical across all of them.

Indistinguishable by type

The rate limits page says so directly:

What "until access resumes" means is spelled out too: "Once you reach your tier's spend cap, API usage pauses until 00:00 UTC on the first day of the next month, unless you request a higher limit sooner." The response body carries the date:

So this is not a hidden failure. The message names the day. The problem is that nothing in the shape your code inspects first — status 429, type rate_limit_error — distinguishes a wait of twelve seconds from a wait of three weeks.

The retry nobody wrote

Here is the part that makes it a real outage rather than a curiosity. You may never have written a retry loop at all:

Rate limits are on the list. The spend-cap error is a rate limit as far as the SDK's classifier is concerned, so every request from every user of your app spends three attempts hammering a wall that will not move until the month turns — and then surfaces as a RateLimitError that your own handler, quite reasonably, may retry again. The code doing the damage is code you never saw.

This is not a reason to disable SDK retries. For the real rate limit they are exactly right. It is a reason to catch the exception and look one level deeper before letting anything retry.

Read the field, then branch

The docs give you the discriminator by name:

Lead with that field. The missing retry-after header is the symptom the docs describe, and a fine second signal, but a future response shape could add a header and the field is the documented contract. In the SDKs, the parsed error body is on the exception:

Three things happen at that branch. The request stops being retried. Someone who can raise the cap finds out today rather than at month end. And every other request stops paying for a wall nobody can push through.

The limit you set yourself is a different error

Two neighbours, both verified on the same pages, both worth a branch of their own.

Your own spend limit is a 400, not a 429. "When usage reaches a spend limit you set, requests return HTTP 400 with error type invalid_request_error." The message begins "You have reached your specified API usage limits" (or the workspace variant). Same feeling for your users, different exception class, and the SDK does not auto-retry a 400 — so this one at least fails fast. The exception is the Claude Code workspace, whose limits "can instead receive a 429 that carries a retry-after header".

And the myth this page is not about. A common belief is that a large max_tokens eats into your output-tokens-per-minute budget up front. It does not: "OTPM rate limits are evaluated in real time as output tokens are produced, counting only the actual tokens generated. The max_tokens parameter does not factor into OTPM rate limit calculations, so there is no rate limit downside to setting a higher max_tokens value." If you were lowering max_tokens to avoid 429s, you were solving a problem that does not exist.

Related: output token costs covers what the reply actually costs, which is the other half of a bill that hits a cap; the agent loop covers the loop that multiplies every one of these requests.

Sources: Claude Platform docs — Rate limits (Spend limits → Reaching your spend cap; Rate limits; Cache-aware ITPM); Claude API errors (HTTP errors, SDK retry behaviour). Verified 2026-09-16. Tier caps are Anthropic's own and change; Claude Platform on AWS differs.