Claude Code Usage Limit Reached? 10 Causes and Fixes

30-second test: read the message. You've hit your session limit or weekly limit is your subscription allowance: start at cause 1. You've hit your Opus limit or Sonnet limit only covers that model family, so /model and a model outside the family keeps you working right now (cause 6). Request rejected (429) or Credit balance is too low isn't a plan limit at all: run /status and go to cause 2.

A usage limit isn't an error in the usual sense. Nothing is broken: your plan's allowance for the current window is used up, and Claude Code blocks requests until the reset time in the message. The useful questions are which limit you hit, and why you got there so fast.

Which limit is it?

Two facts explain most "how did I hit it already?" moments. First, usage counts against the session and weekly limits at the same time, so one heavy burst can use up the week before the five-hour window resets. Second, Claude Code charges by tokens, and every request carries your whole conversation. A session that's been open all day costs more per message than a fresh one, even for a one-line question.

Step 1: see where the usage went

Run /usage (/cost and /stats are aliases). On a Pro, Max, Team or Enterprise plan it shows your plan usage bars, when each window resets, and a breakdown of what counted against your limits:

• Attribution: recent usage split across skills, subagents, plugins and individual MCP servers, as a percentage of the total.
• Recommendations: one row per change worth making, each starting with the share of your recent usage it applies to, such as 25% Trim ~/code/api/CLAUDE.md · 49k tokens per request. The share is how much usage the row covers, not how much the change saves.
• Loops: the heaviest /loop and other session-scoped scheduled tasks that ran recently.

Press d or w to switch between the last 24 hours and the last 7 days. On v2.1.305 or later, a footer hint such as f to fix 2 of 3 means you can press f and Claude Code applies the recommendations it can, showing you each change before making it. One catch: the breakdown is computed from session history on this machine, so usage from other devices or claude.ai isn't in it, even though it counts against the same limits.

If /usage says something like rate limited until 3:14am, that only means Claude Code can't refresh your plan figures until then. It isn't a limit on your work.

10 causes, in the order to check them

1. Your claude.ai chats and Claude Code share one allowance. On Pro and Max, the five-hour session limit and the weekly limit are shared across Claude and Claude Code, and Claude Code in VS Code, Cursor or JetBrains counts against the same limits as the terminal. A long research chat in the browser this morning is part of why Claude Code stopped this afternoon. Max plans also have a separate weekly limit for Fable.
2. You aren't on your subscription at all. If ANTHROPIC_API_KEY is set and you approved it, Claude Code uses that key instead of your Pro or Max login, so you're billed at API rates and limited by that key's tier. The same goes for ANTHROPIC_AUTH_TOKEN, which outranks the API key, and for cloud provider settings such as CLAUDE_CODE_USE_BEDROCK, which outrank both. Run /status to see which credential is active; when a login and an API key are both configured, it marks the one that isn't in use. To go back to your plan, unset ANTHROPIC_API_KEY, remove it from your shell profile and relaunch, or turn off Use custom API key in /config (the toggle only shows while the variable is set). In -p runs the key is always used when present. What a 429 or Credit balance is too low means on that path is covered in Claude Code API errors.
3. One session doing everything all day. Each time Claude uses a tool, Claude Code sends another request carrying the conversation so far. Prompt caching makes re-reading that history cheaper, but it still draws usage on every turn. /clear between unrelated tasks costs nothing; run /rename first if you want to find the session later with /resume. A /compact is itself a large request because it reads everything it summarizes, so compact at a natural break rather than mid-task. If the window fills fast and auto-compact keeps firing, Claude Code context filling up fast has nine fixes.
4. Coming back after a break. Cached context expires after a period of inactivity. On a subscription within your plan's included usage, Claude Code asks for a one-hour cache on the main conversation; subagents and other side requests get five minutes. After a longer gap, your first message reprocesses the whole context uncached, which is also why /compact costs the most right after you resume an old session. For a big session you only half need, /clear and a short summary of where you were beats resuming it cold.
5. A large starting context. CLAUDE.md, MCP tool listings and skill descriptions are sent with every request before you type anything. Anthropic suggests keeping CLAUDE.md under 200 lines and moving workflow-specific instructions into skills, which load only when used. Run /mcp to disable servers you aren't using, and prefer CLI tools like gh where they exist, since they add no per-tool listing. /context shows what's taking the space.
6. Opus as the everyday model. Sonnet handles most coding tasks well and costs less than Opus; Anthropic suggests saving Opus for complex architectural decisions and multi-step reasoning. Switch with /model, or set a default in /config. A switch to Opus also applies to subagents that inherit your session's model. Two side effects worth knowing: each model has its own prompt cache, so the first request after any switch re-reads the whole conversation with no cache hits, and opusplan (Opus in plan mode, Sonnet for execution) makes every plan-mode toggle a model switch.
7. More reasoning than the job needs. Extended thinking is on by default, and thinking tokens are billed as output, often tens of thousands of tokens per request. For routine work, lower the effort level with /effort (for example /effort low) or in /model. On models with a fixed thinking budget, MAX_THINKING_TOKENS lowers it; adaptive-reasoning models ignore a nonzero budget, so use effort there. Changing effort mid-session also costs one cache miss, so set it at the start of a task.
8. Subagents and parallel work. Every subagent sends its own requests on top of the main conversation's. Handing a big read to a subagent keeps your context small, but it isn't free, and a wide fan-out of parallel subagents is exactly the kind of burst that can use up your weekly limit inside one session window. Give simple subagents a cheaper model with model: haiku in their configuration, or set CLAUDE_CODE_SUBAGENT_MODEL to choose the model for subagents that don't get one another way. /tasks shows which model each running subagent uses (v2.1.242 or later), and the /usage attribution shows the subagent share.
9. Agent teams. Each teammate is a separate Claude instance with its own context window, so token use rises roughly with team size. Anthropic's costs page puts teams at about 7x the tokens of a standard session when teammates run in plan mode. They're off by default (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 turns them on). If you use them, keep teams small, use Sonnet for teammates, keep spawn prompts short and shut teammates down when they finish, because an active teammate keeps using tokens until it exits.
10. Work that runs while you're idle. A session-scoped scheduled task, such as a /loop, fires on its interval even when you're not there, sending your full context each time. Messages from your other sessions and goal check-ins can also start new turns in an idle session. The /usage Loops rows show the heaviest scheduled tasks, so stop the ones you don't need. Background jobs like summarizing conversations for claude --resume use a small amount too, typically under $0.04 per session, and prompt suggestions send a small, mostly cached request after each reply.

Already blocked: your options

• Wait, and let Claude Code continue for you. On v2.1.234 or later, an interactive session signed in with claude.ai waits and resumes the interrupted task after the reset. You'll see Continuing automatically at 3:45pm · esc to cancel. Keep the session open; Claude Code picks the task back up without resending your last message, and still asks for permissions as usual. Press Esc at an empty prompt to cancel, or run /rate-limit-options to choose. Claude Code doesn't start the wait on its own for a reset more than 24 hours away, such as a weekly limit days out, but you can pick Wait here, then continue automatically from that menu. To turn it off, switch off Continue automatically at usage limit in /config. There's no wait to offer with API keys, cloud providers, background sessions or -p runs.
• Switch model, for a family limit. After You've hit your Opus limit or Sonnet limit, /model and a model outside that family keeps you going. It won't help with the session or weekly limit.
• Turn on usage credits. /usage-credits opens Settings > Usage on claude.ai for Pro and Max, or sends a request to your admin on Team and Enterprise. Once your included usage runs out, requests continue at standard API rates until you reach your monthly spend limit or your balance runs out. You'll see the message change to "Now using credits". Usage credits don't change when your windows reset, and the monthly API credits that come with Max plans can't be used for them. The command isn't available when you sign in with an API key.
• Upgrade, or use the API for a sprint. Anthropic's help center suggests Max 5x for Pro users who hit limits regularly, Max 20x for Max 5x users, or a Claude Console account with API credits for intensive coding sprints. If you go the Console route, /login switches accounts.

On Pro and Max, if you hit the five-hour limit while Claude Code is partway through a response, it may keep working briefly to finish that step and show Usage limit reached · wrapping up. That allowance is small, counts toward your weekly limit, and is still rolling out.

See it coming next time

Before a window runs out, Claude Code can warn you with a message like You've used 85% of your session limit · resets 3:45pm. To watch it all the time, put the rate_limits.five_hour.used_percentage and rate_limits.seven_day.used_percentage fields in your status line (they're present for Pro and Max subscribers after the first response). Our free status line builder writes a tested script that shows them, in your browser.

On an API key instead? Limits work differently

With a Console API key there are no session or weekly windows. You pay per token, and your organization has a usage tier with a monthly spend cap plus per-model rate limits measured in requests, input tokens and output tokens per minute. Capacity refills continuously rather than resetting on a schedule, and a 429 with a retry-after header tells you how many seconds to wait. Hitting a spend limit you set yourself returns You have reached your specified API usage limits instead. The fixes for that side, including retry settings for CI and the auto-created "Claude Code" workspace's own limits, are in Claude Code API errors. If Claude Code just sits on Retrying with no error, see Claude Code stuck or not responding.

Facts on this page come from Anthropic's Claude Code docs on managing costs, errors, interactive mode, commands, authentication, prompt caching, model configuration, subagents, agent teams and the status line, the Claude Help Center articles on using Claude Code with Pro or Max, usage credits and usage and length limits, and the Claude API page on rate limits. This guide isn't affiliated with Anthropic.

A lean setup is the cheapest way to stretch your allowance. Our Claude Code Power Config Pack has 6 lean CLAUDE.md templates, permission presets and 8 tested safety hooks, $6 with the launch code while it lasts.

Not ready to buy? Our free safety hooks block risky commands before they run.