Four different things get called "the limit" in AI coding tools, and two of them share the name rate limit while having nothing to do with each other. If you debug the wrong one, you can spend an afternoon building backoff logic for a problem that backoff cannot fix.
The distinction that resolves most of it: a rate limit is a ceiling on how fast you may send requests. A usage quota is a ceiling on how much you may consume. One is a speed bump. The other is a fuel gauge.
Four limits, four owners
| Limit | What it meters | Where it lives | What resets it | Correct response |
|---|---|---|---|---|
| API rate limit | Requests and tokens per minute | An API key, project, or org | Continuously, within seconds to minutes | Back off and retry; it clears itself |
| Subscription usage window | Allowance consumed over hours and days | Your Pro / Max / Plus plan | A rolling window or a fixed anchor | Wait for the printed time, switch model, or buy capacity |
| Context window | How much text one conversation can hold | The session itself | Starting fresh, or compacting | /clear or /compact — no waiting involved |
| Spend limit / credits | Money or prepaid balance | A billing account | You topping it up, or the period rolling | Change the budget, or continue at API rates |
The third row is the one most often mistaken for a usage limit, because a context error and an allowance error can both arrive in the middle of a long session. They are unrelated: one is about the size of the conversation, the other about your account's budget. Compacting frees context and restores zero allowance.
The two things both called "rate limit"
Anthropic's API documentation defines rate limits in one line: they set the maximum number of API requests an organisation can make over a defined period. Concretely, that means requests per minute, input tokens per minute, and output tokens per minute, set by your usage tier, and an exceeded limit returns HTTP 429 with a retry-after header.
Now compare that vocabulary to the message your terminal prints on a subscription plan. No status code, no retry-after, no requests-per-minute anywhere. Instead it names a limit and prints a reset time. That is not the same system with different wording; it is a different system.
The practical consequence is worth stating plainly: if you are signed in with a subscription, an API rate limit is not what is stopping you. Those ceilings belong to Console or cloud-provider accounts and are billed per token. Loading a subscription error into backoff logic is a category error.
The signal is mechanical rather than interpretive. A retry-after header means an API rate limit, and it typically clears on its own in under 60 seconds. A printed reset day means a subscription allowance, and it will not clear for up to 7 days.
The trap in promotions that raise "rate limits"
Marketing copy blurs the two on purpose, and the blur has a cost.
When a vendor announces higher rate limits, the honest question is: throughput or allowance? Doubling requests-per-minute does not add a single unit to your weekly pool. And it can make your situation worse in one specific way — sending the same work faster drains a fixed allowance sooner. You finish your week's budget on Wednesday instead of Friday and conclude the change was a downgrade, which from your side it was.
So the check before you celebrate any limit announcement is a single question: does this raise how fast I may send, or how much I may send? Only the second one extends how long you can work.
Why the two failures feel so different
A rate limit is momentarily annoying and self-healing. You wait 90 seconds. Nothing about your day changes.
A usage quota failure is structural. It does not clear because you were patient; it clears when the window rolls or the anchor arrives — which can be 7 days away. That asymmetry is why quota failures generate far more frustration than their frequency would suggest, and why retrying — the correct response to the first — is close to the worst response to the second.
There is also a messaging difference that adds confusion. Rate limits are designed to be retried: the client is expected to try again. Quotas are designed to stop you: retrying produces the same error, immediately, forever, until the clock moves. Systems that retry politely on rate limits and hammer on quotas hit the wrong wall twice.
Most rate limits are burst events. A batch job, a test suite, or an agent loop trips the ceiling and the failure clears about 20 seconds later when the burst ends — which is why the symptom can look intermittent and unrelated to anything you changed.
Telling them apart without documentation
Three checks, cheapest first:
- Is there a
retry-afterheader or a seconds-scale hint? API rate limit. It will clear itself; wait and retry. - Does the message name a day, a specific time, or a limit type? Subscription allowance. Only that time passing changes anything.
- Does the usage view show headroom? If your usage bars look fine and you are still blocked, you are not looking at a quota failure at all — suspect a per-model cap or a context limit instead.
FAQ
Does raising my API tier increase my subscription allowance? No. They are separate systems. API tiers govern requests and tokens per minute on API keys; a subscription's allowance is set by the plan, and the vendor generally does not publish the number.
Can I make a rate limit stop happening? You can reduce how often you hit it — batching similar requests, caching results, avoiding redundant calls. You cannot raise the ceiling by being well-behaved. The ceiling is a property of the account, not of your etiquette.
Is a 429 always a rate limit?
In API contexts, it signals that requests are being rejected for exceeding a limit, most often a rate limit — and the retry-after header is the part that matters, because it tells you how long to wait. If you are on a subscription and never see a status code, you are not in this system.
Why do subscription providers not publish their quota numbers? Anthropic states that the plan-level numbers are not published, and describes plan differences in relative terms instead. Where a vendor does not publish a figure, any exact number you read elsewhere is someone's estimate, however confidently it is written.
Sources
- API rate limits — Anthropic. Requests-per-minute and tokens-per-minute ceilings by usage tier, and the 429 /
retry-afterbehaviour. - Models, usage, and limits in Claude Code — Anthropic. How subscription usage is metered, and how it differs from API-key billing.
- Codex pricing and usage limits — OpenAI. The documented window structure on the subscription side.
For reading the subscription error itself — which of the three caps you hit, and which response actually works — see "You've hit your usage limit": what each error actually means. For why a quota failure can only be answered by a notification rather than a calculation, see Three kinds of reset.