Claude Code rate limit errors: which limit did you actually hit
Plan windows, API key limits, server throttles and overload errors look alike in the terminal. The message text tells them apart.
By ClaudeGPT Si Newsroom, Editorial team
3 min read
A Claude Code rate limit can mean four different things, and the error text tells you which. If it says "You've hit your session limit" or "weekly limit", your plan window is used up and resets at the time shown; a 429 or "temporarily limiting requests" is a throttle on the API side. To see plan limits coming before they stop you, run /usage or keep UsageAtlas, a free, open-source desktop tracker, open beside your editor.
Read the error first
Claude Code's error reference separates these cases clearly. Here is the short version.
| Message | What hit you | What to do |
|---|---|---|
| You've hit your session limit · resets 3:45pm | Your plan's rolling five-hour window | Wait, use /usage-credits, or let Claude Code continue after the reset |
| You've hit your weekly limit · resets Mon 12:00am | Your plan's weekly window | Same options; this one takes longer |
| You've hit your Opus limit (or Sonnet) | A limit on one model family | Switch to a model outside that family with /model |
| API Error: Request rejected (429) | The rate limit on your API key or cloud project | Check the credential with /status, lower concurrency |
| Server is temporarily limiting requests (not your usage limit) | A short server-side throttle | Retry; Claude Code already retries with backoff |
| 529 Overloaded | API capacity | Retry later or switch models; it does not use your quota |
The first three are plan limits. The last three are not, which is why switching plans or waiting for a reset does nothing for them.
The stray API key problem
A common surprise: you pay for Pro or Max, yet you get a 429 tied to an API tier. Anthropic's docs point at one cause. If ANTHROPIC_API_KEY is set in your environment, Claude Code uses that key instead of your subscription. Run /status to see which account and credential are active, and unset the variable if it is not the one you meant to use.
On a Console API account, Claude Code traffic also counts toward your organization's API rate limits. Admins can set a workspace rate limit on the Claude Code workspace so it cannot starve production jobs.
Watching plan limits before they bite
The plan windows are the ones you can plan for. Claude Code gives you three built-in views:
/usageshows plan usage bars and a breakdown of what used them, such as subagents or MCP servers.- A custom status line can print
rate_limits.five_hourandrate_limits.seven_day, each with percent used and a reset timestamp, on Pro and Max. - A warning such as "You've used 85% of your session limit" appears before a window runs out.
These live inside the terminal. If you would rather see the numbers without a session open, UsageAtlas for Claude Code shows the supported five-hour and weekly windows, what is left, local reset times and history on your desktop. You set a threshold per window and get one alert per reset cycle. It runs on Windows, macOS and Linux, needs no account for local tracking, and never reads your prompts. It also tracks Codex, Cursor and Copilot, handy when you move to another tool while Claude Code resets.
A status line script is still the better fit if you want the figure inside the terminal and nowhere else. Both read the same data Claude reports, so you can run them together.
Cutting how fast you hit it
The /usage breakdown often names the cause. Long-running sessions resend the whole conversation on every request, so /clear between unrelated tasks helps. Parallel subagents each send their own requests. Picking a smaller model for routine subagent work stretches a window further.
FAQ
Does a 429 count against my plan limit?
A "Request rejected (429)" comes from the API key or cloud project limit, not the subscription window. Check /status to confirm which credential sent it.
Can Claude Code resume on its own after a plan limit? Yes, from v2.1.234 in interactive sessions signed in with a subscription. It waits in the open session and continues the task after the reset; press Esc to cancel.
Is UsageAtlas free? Yes. It is free and open source under the MIT license.