Claude Code Retries Rate-Limit Errors for API Keys, Not for Max Plans
Your Claude Code session can die instantly due to a single error.
If you use an API key, the system retries the request. If you use a Max plan, the session ends.
I decompiled the Claude Code binary (version 2.1.179) to find out why. The logic is simple. The code checks how you pay before deciding to retry a 429 error.
The logic works like this:
- API keys: The system retries the error.
- Enterprise accounts: The system retries the error.
- Pro and Max plans: The system does not retry. The error kills your work.
This happens because the client identifies your subscription type. It sees your OAuth token and skips the retry path.
There is a reason for this design. A 429 error on a subscription often means you hit a usage limit for the next few hours. Retrying a usage limit is useless. It wastes resources.
But there is a problem with this approach.
Anthropic limits come in two types:
- Long usage windows (hours).
- Short per-minute limits (seconds).
The code treats both the same. It does not distinguish between a limit that lasts hours and a limit that lasts two seconds.
When you hit a short per-minute limit on a Max plan, you lose your entire run. If you were using an API key, the system would wait two seconds and succeed.
This means your reliability depends on your billing tier.
If you build agentic workflows on a subscription, you are trusting a system that gives up easily. A two-second blip becomes a failed task for you, but a minor pause for someone else.
You can test this yourself. Watch your logs for the anthropic-ratelimit-unified-status header.
- If you use a metered key, you will see retries.
- If you use Max, you will see the session die.
Reliability is a part of what you buy. In this case, the rules change silently based on your payment method.
Optional learning community: https://t.me/GyaanSetuAi