OmniscioGuidesRate limit reached
Claude Code API Error: Rate limit reached
This is a 429 — the status code for too many requests — and it is not your plan's five-hour allowance, which prints its own message naming a reset time. Because the line names no limit, the first step is to see which credential the request used.
If you only want the fix, what to do, in order is the section to read. Anthropic's Claude Code error reference has no entry under this exact wording, so the rest sets out the three limits it does document, what separates them, and what public reports add. Every claim is sourced and dated at the end.
Last checked against Anthropic's documentation on November 16, 2026. By the Omniscio team. Updated .
The message, and the wordings Anthropic documents instead
API Error: Rate limit reachedThe line people arrive with. On November 16, 2026 we searched it word for word through Anthropic's Claude Code error reference, its API error list and its rate limits reference, and it appears in none of them.
Calling it a 429 is our reading, not Anthropic's wording: the line is none of the plan's messages, and it arrives where the documented 429s do.
What those pages document instead are three limits, each with its own wording:
API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.The 429 entry: the rate limit configured for your API key, Amazon Bedrock project or Google Cloud project.
API Error: Server is temporarily limiting requests (not your usage limit)A short-lived throttle unrelated to your plan quota, which Claude Code tells apart from a plan limit by the absence of the extra identifying headers a real limit response carries.
You've hit your session limit · resets 3:45pmYour plan's allowance, with the reset time in the message.
- What a 429 is, in Anthropic's words
- Why it can appear with quota left
- What Claude Code tried first
- What to do, in order
- Which limit stopped you
The overloaded and 429 errors guide covers the documented 429 and 529 messages in depth. The usage limits guide covers the plan's own windows and resets.
What a 429 is, in Anthropic's words
A 429 is the status code for too many requests.
Anthropic's API error list defines it as a rate_limit_error and names three ways to reach it.
Your organization hit a rate limit, reached the monthly spend cap on its usage tier (the rate-limit band its API account is on), or reached a spend limit on its Claude Code workspace (a shared Claude Code setup an organisation runs in the Claude Console).
On an Anthropic API key, limits are measured in requests per minute, input tokens per minute and output tokens per minute for each model class, and exceeding any of them returns a 429 describing which limit was exceeded.
Two rules decide what to do next:
- The
retry-afterheader holds the number of seconds to wait, and Anthropic notes that earlier retries can fail. Not every 429 carries it. A spend-cap 429 never does, and retrying that one fails until access resumes: once the tier's monthly cap is reached, API usage pauses until 00:00 UTC on the first day of the next month. - Ramp limits cap how fast your usage on a model can grow, so a sharp rise can return a 429 while you are under your per-minute limits. Anthropic's advice there is to wait at least the
retry-aftertime, hold traffic at a level where requests succeed, then increase it by at most one step per minute.
The rate limits reference adds one more place limits come from: a Claude Code workspace's limits are checked separately, and requests over them can receive a 429 that does carry a retry-after header.
Sources: Anthropic API errors and the rate limits reference for the units, headers, spend cap, ramp limits and the workspace limit. All read November 16, 2026.
Why it can appear with quota left
A common complaint about this line is that it arrives while the usage page shows room. That is possible because the allowance you can see and the limit that answered are different meters, and one of them is per model.
Anthropic documents part of it plainly: a model family can carry its own cap — Opus and Sonnet each have one — while the session and weekly limits are shared across all models. So a message that names no limit can come from a family-level one.
The rest comes from public reports on Anthropic's tracker, which are reports rather than Anthropic confirming a cause. Read them as evidence that the same short line covers more than one condition:
- Issue #25805, opened on February 14, 2026, argues the wording does not distinguish a usage limit from a throughput limit, and gives one reproduction: 32% session usage and 98% weekly usage, then the bare message. It was closed on June 4, 2026.
- Issue #56633, opened on May 6, 2026, reports the bare message appearing when a model was at capacity, while
/statusshowed 5% session usage and 1% weekly usage. It was closed by a bot on July 6, 2026 for inactivity, not by a fix. - Issue #29579, opened on February 28, 2026 and still open, reports it on a paid plan with 16% usage shown. Issue #28975, opened two days earlier and also open, pins it to one model with the extended context window.
- Issue #40584, opened on March 29, 2026, reports the error appearing after hours of inactivity in a very large session, with the reporter's own diagnosis that no API call was made at all. That is the reporter's reading of their logs, not a documented behaviour. It was closed by the project's inactivity bot on May 24, 2026.
An exact phrase search on Anthropic's tracker returned 98 issues carrying this full line in their title on November 16, 2026, which is a measure of how often the same question is asked, not of one cause.
What that means in practice: the message alone cannot tell you which limit fired, so check the credential and the model first, then treat a long retry-after time as a real cooldown rather than something a resend clears.
Sources: the session-limit entry of the error reference; the five issues named above, their opening posts, states and dates, all read November 16, 2026, plus a GitHub search of the repository for the exact phrase.
What Claude Code tried first
Claude Code retries transient failures up to 10 times with exponential backoff — waiting longer between each attempt — before showing you a message, and temporary 429 throttles are on that list.
A gateway, the other word that keeps coming up here, is a server an organisation puts between Claude Code and Anthropic. Three exceptions matter for the retries:
- A gateway's spend-limit 429 is not retried, because Anthropic's reference says it is not a throttle.
- On a claude.ai subscription, 429 throttles that do not carry your plan's limit headers are retried, as of version 2.1.199; the reference notes that earlier versions failed the turn on the first occurrence for subscription sign-ins.
- A 429 that carries your plan's limit headers is the plan's own allowance rather than a throttle, and the reference documents that allowance separately, as a block until its reset time.
In an unattended job such as a CI run, setting CLAUDE_CODE_RETRY_WATCHDOG=1 in the environment the CLI runs in makes Claude Code retry 429 and 529 capacity errors without the usual limit instead of failing after the retry count.
The same reference notes that it fails at once when a standard-speed request gets a 429 reporting a spend limit or exhausted usage credits, even one from a gateway spend cap.
While a retry runs, the spinner counts it down as Retrying in Ns · attempt x/y, and the label names a rate limit from the first attempt.
Sources: the automatic retries and tune-retry-behavior sections of the error reference, read November 16, 2026.
What to do, in order
- Run
/statusand look at the credential. A strayANTHROPIC_API_KEYin your environment routes requests through that key instead of your subscription, which is how a rate limit shows up for someone who believed they were on a plan. - Run
/usageto rule the plan windows out. It shows the plan's limits and when each resets, so one glance tells you whether this is your allowance. - Wait, then resend. If you call the API directly, the response carries a
retry-afterheader holding the seconds to wait, and Anthropic notes that earlier retries can fail. In a session you see the message rather than the header, so pause a minute or two before sending again. - If one model family is capped, switch families. The Opus and Sonnet limits apply only to requests to that family, so
/modelto a model from another family keeps you working. - Send less at once. Anthropic's 429 steps are to avoid running many parallel subagents, and to switch to a smaller model with
/modelfor high-volume scripted runs. Ramp limits ask the same thing at a slower pace: hold traffic where requests succeed and raise it by at most one step per minute. - Check the provider console. For an API key, the Rate limits page in the Claude Console shows the tier and limits in force, and is where a higher tier is requested.
Two cases look like a rate limit and are handled differently. With fast mode on, hitting its limit drops you to standard speed on its own, grays the ↯ icon for the cooldown and re-enables fast mode when it expires; /fast switches it off by hand.
And a 1M-context model on a plan that does not include that context prints its own message naming /usage-credits and /model. If the documented 429 message appears at all, its closing sentence names status.claude.com, or the provider's status page, for a capacity cause.
Sources: the 429 and session-limit entries of the error reference, the rate limits reference for the tiers, headers and ramp guidance, and the fast mode page for its separate limits. All read November 16, 2026.
Which limit stopped you
Match what is on screen to a row, then take that row's step. A message that names nothing is the case this page is about.
- Names a reset time, such as
resets 3:45pm, and names no model: your plan's shared session or weekly allowance. Wait for the reset. - Names a reset time and a model family, such as
You've hit your Opus limit · resets 3:45pm: that family's own cap./modelto another family, such as Sonnet when Opus is capped. Server is temporarily limiting requests: a throttle, unrelated to your quota. Wait briefly, then check the status page if it persists.Request rejected (429): a configured rate limit on the key or provider project./status, then the provider console.- Only
Rate limit reached: nothing named, so work the "What to do" list in order, starting with/status.
The 529 is the other one worth ruling out, because a busy API and a rate limit feel the same from the keyboard and are not: a 529 is capacity across all users, is not your usage limit, and does not count against your quota. The overloaded and 429 guide covers it in full.
If the text after API Error: reads like a web page rather than a sentence, something between you and the API answered in its place; the connection errors guide covers that family.
Running several sessions at once
A limit is easier to ride out when sessions are spread across your login accounts, because one account at its limit then affects only its own sessions. Omniscio, the desktop app we make, does that, and shows a maxed account's sessions as waiting rather than live.
The page on distributing sessions across accounts covers it, and the per-model switch page covers the case where a single model runs out: a switch to your backup model that ships off until you turn it on.
Where these answers come from
- Anthropic's Claude Code error reference, for the documented 429, throttle and session-limit messages, the retry rules and the retry variables.
- Anthropic API errors, for
rate_limit_errorand the three ways to reach a 429. - Anthropic API rate limits, for the units, the
retry-afterheader, the monthly spend cap and ramp limits. - Fast mode, for its separate rate limits and cooldown.
- Claude Code issues #25805, #56633, #29579, #28975 and #40584, for what people report seeing.
All of the above were read on November 16, 2026. The exact wording in this page's first message block was searched for through three Anthropic references that day and found in none of them; if a later release documents it, that paragraph is the one to rewrite.
Common questions
What does API Error: Rate limit reached mean in Claude Code?
It is a 429, the status code for too many requests: the API refused this one because a rate limit was reached. It is not your plan's five-hour allowance, which prints its own message naming a reset time. The bare line names no limit, which is why the first step is to see which credential the request used.
Why does Rate limit reached appear when my usage page shows quota left?
Because the plan allowance you can see and the limit that answered are different meters. One is measured in requests and tokens per minute for a model class, another is a model family's own cap, and a sharp rise in usage can hit either while your weekly allowance still has room.
Public reports describe exactly this gap, and none of them is Anthropic confirming a cause.
Is Rate limit reached the same as You've hit your session limit?
No. The session-limit message names a reset time and blocks requests until then. Rate limit reached names nothing, and Anthropic's reference separates it from the plan allowance: its 429 entry is about the rate limit on your API key, your Amazon Bedrock project or your Google Cloud project.
Can a proxy or gateway cause it?
It can change what you see. When a proxy, load balancer or gateway answers with its own HTML 429 page, the text after the dot in Claude Code's 429 message is that page's title, and before version 2.1.281 the whole page's markup was printed there.
A response that reads like a web page rather than a sentence points at the machine in between.