Rate Limit Helper

Rate limits are not one thing

The single biggest reason people stay stuck on a rate limit is that they treat all of them the same. There are at least four different limits that produce different messages and need different responses: a per-minute request cap (429), a subscription usage cap ('you have reached your usage limit'), a token-throughput cap (tokens per minute), and a concurrency cap. And there is a fifth message - 'overloaded' or 529 - that looks like a rate limit but is actually the service being busy, which is not your limit at all. Pick your symptom above and this tool tells you which one you hit and exactly what to do.

The right move depends entirely on the type. A 429 clears in about a minute if you just slow down. A subscription usage cap needs you to wait for the rolling window to refill or step up a tier. A token-throughput limit needs smaller prompts, not fewer of them. Getting the diagnosis right is most of the fix.

The four limits and the one impostor

• 429 request-rate limit - too many requests per minute. Fix: slow down, honor retry-after, back off. Clears fast.
• Subscription usage cap - your Pro/Max allowance for the rolling window is spent. Fix: wait for refill, use a lighter model, or move to a higher tier / the API.
• Token-throughput limit (tokens per minute) - a few huge prompts blew the token ceiling even at low request count. Fix: shrink prompts and cap output.
• Concurrency limit - too many requests in flight at once, usually from parallel sessions. Fix: reduce parallelism, serialize the work.
• Overloaded / 529 - the impostor. This is Anthropic at capacity, not your limit. Fix: wait and retry with backoff. Nothing you did caused it.

How to back off correctly

1. On the first rate-limit error, wait - do not immediately retry into the same wall.
2. Use exponential backoff: 1 second, then 2, then 4, then 8, doubling each time.
3. Add jitter - a small random amount on each wait - so many clients do not all retry at the same instant.
4. Cap the backoff at a sane ceiling (say 30-60 seconds) so you are not waiting forever.
5. If a retry-after header is present, use it instead of your computed backoff for that attempt.
6. Give up after a few attempts and surface the error rather than looping forever.

Subscription cap vs API limit - which are you on?

If you use Claude Code through a Pro or Max subscription, your ceiling is a usage cap that refills on a rolling window - hitting it means 'come back later or upgrade'. If you use the pay-as-you-go API, your ceilings are rate limits (requests and tokens per minute) tied to your usage tier, and they clear within the minute. The messages differ: subscription caps say things like 'you have reached your usage limit', while API rate limits return a 429. Knowing which side you are on tells you whether the answer is 'wait for the window' or 'slow down for a minute'.

Preventing the next one

Most repeated rate limiting comes from three habits: running too many parallel sessions against one account, pasting giant files into every prompt, and defaulting to the heaviest model for routine work. Fix those three and the limits mostly stop appearing. Reserve the big model for hard reasoning, keep prompts lean and let the model read file paths instead of pasting whole files, and cap how many sessions run against a single account at once. If your steady-state volume genuinely exceeds a subscription, the API with the right usage tier is the built-for-it answer.

When to upgrade instead of wait

Waiting is free but it costs you flow. If you hit your cap once a week, wait it out. If you hit it every single day and it is blocking real work, the math flips - a higher tier or the API removes the fixed ceiling and pays for itself in recovered time. The ROI Calculator on this site can put a dollar figure on that lost time so the upgrade decision is evidence-based rather than a guess.