Claude Code "Server is temporarily limiting requests" explained
This Claude Code message is a short server-side throttle, not your plan limit. What it means, how retries work, and how it differs from 429 and 529 errors.
"API Error: Server is temporarily limiting requests (not your usage limit)" means Anthropic's API applied a short-lived throttle that has nothing to do with your plan's quota. You have not run out of anything. On Claude Code v2.1.199 or later it is retried automatically before you ever see it, so if it does reach you, wait briefly, try again, and check status.claude.com if it keeps happening.
What the message is
Anthropic's Claude Code error reference lists it in the "Usage limits" section, but flags it as one of the entries that work differently: it is "a server-side throttle unrelated to your plan quota". The full text is:
API Error: Server is temporarily limiting requests (not your usage limit)
Claude Code tells this throttle apart from a real plan limit by what the response carries. Per the docs, a real limit response includes unified quota headers, and this one does not. That is why the message can say "not your usage limit" with confidence.
The distinction matters because the fixes are opposite. A plan limit needs a reset, usage credits or an upgrade. A throttle needs nothing but a short wait. A real limit also reads differently, for example "You've hit your session limit · resets 3:45pm". For those, see what to do when you hit the session limit and the weekly limit.
Automatic retries
Claude Code "retries transient failures up to 10 times with exponential backoff before showing you an error", and temporary 429 throttles are on its list of retried failures. While it retries, the spinner shows a Retrying in Ns · attempt x/y countdown after an error label. So when the message does reach you, Claude Code has already tried several times.
Your version matters here. As of v2.1.199, this throttle is retried with backoff "whichever way you authenticate". On earlier versions, a session signed in with a claude.ai subscription failed the turn on the first occurrence; only API key and Enterprise sign-ins retried it. If you are on a subscription and see this message often, check claude --version and update if you are older than 2.1.199:
claude update
The retry count is adjustable with the CLAUDE_CODE_MAX_RETRIES environment variable (default 10). It is capped at 15 as of v2.1.186, and Anthropic suggests lowering it in scripts to surface failures faster (errors, environment variables). Most people never need to touch it.
What to do
- Wait. Let the retry countdown run.
- If the error is shown after the retries, pause and send your message again. Anthropic's advice for this entry is simply "Wait briefly and try again".
- If it persists, check status.claude.com.
- On a subscription, make sure you are on v2.1.199 or later so the throttle is retried for you.
You do not need to buy usage credits, switch plans or wait for a reset for this message.
How it differs from similar errors
Several messages look alike but have different causes. This is how Anthropic's reference describes them:
| Message (start of the text) | What Anthropic says it means |
|---|---|
| "API Error: Server is temporarily limiting requests (not your usage limit)" | A short-lived throttle unrelated to your plan quota. Retried automatically. |
| "You've hit your session limit" or "You've hit your weekly limit" | A plan allowance is used up. Claude Code blocks requests until the reset time shown. |
| "API Error: Repeated 529 Overloaded errors" | The API is temporarily at capacity across all users. Not your usage limit, and it does not count against your quota. |
| "API Error: Request rejected (429)" | You hit the rate limit configured for your API key, Amazon Bedrock project or Google Cloud project. |
The 529 overloaded error
For a 529, Anthropic writes: "A 529 is not your usage limit and doesn't count against your quota." Capacity is tracked per model, so one of its suggested steps is to run /model and switch to a different model. That is the reverse of a session or weekly limit, where switching models does not restore access.
A 429 on an API key
"Request rejected (429)" is about rate limits on a key or cloud project, not a subscription. Anthropic's first suggested step is to run /status and confirm the active credential, because "A stray ANTHROPIC_API_KEY in your environment can route requests through a low-tier key instead of your subscription." If you pay for a plan and see this one, read why Claude Code bills your API key instead of your plan.
Not every 429 is a throttle, either. The docs note that a gateway's spend-limit 429 "isn't a throttle" and is not retried as one.
Unattended and CI sessions
For jobs that run without you, Anthropic documents CLAUDE_CODE_RETRY_WATCHDOG (Claude Code v2.1.186 or later). Set it to 1 in unattended sessions such as CI jobs and Claude Code retries 429 and 529 capacity errors indefinitely instead of failing after CLAUDE_CODE_MAX_RETRIES attempts. On v2.1.199 or later it also raises the default retry count for other transient errors, such as server errors and dropped connections, to 300, roughly three hours of backoff (environment variables).
Two details are easy to miss:
- It still fails at once when a standard-speed request gets a 429 that reports a spend limit or exhausted usage credits.
- It does wait for plan limits. The watchdog backs off until the limit resets when the response carries a reset time, "so a session that hits a usage limit waits out the remaining window". A weekly reset can be days away. If a CI job should fail rather than hang, cap that wait with
CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS(v2.1.301 or later), or cap the time each request spends waiting out 429 and 529 errors withCLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS(v2.1.295 or later). Both take milliseconds.
This is separate from automatic continue, the interactive feature that waits for a usage limit and then resumes your task. That one is not offered in background sessions or -p runs (interactive mode).
Is it ever your usage?
Not for this message. One thing can confuse the picture, though: a note such as rate limited until 3:14am in /usage means Claude Code cannot fetch your plan limits again until then, "not that your work with Claude is limited" (costs). When that lookup fails, /usage shows the last bars it loaded on the machine within the past 60 minutes, with a "Showing last-known usage" note; press r to retry.
To find out whether you are close to a real limit, run /usage and look at the session and weekly bars.
Checking your real numbers
When something throttles, the useful question is whether you are actually near a limit. Headroom is a free Mac menu bar app that shows session and weekly use for each Claude Code account signed in on your Mac, with reset countdowns. If the percentages are low, you are looking at a throttle or an outage, not your plan. It reads the sign-in Claude Code already saved on your Mac, sends no prompts, and if it cannot read the numbers it says so instead of guessing. It is independent, not made or endorsed by Anthropic. Get it at headroom.everydaymactools.com.