Usage limits

On a Claude subscription (Pro, Max, Team or Enterprise), Claude Code does not bill you per token. Instead, your plan gives you a usage allowance that refills over time, and every request Claude Code sends draws on it. When it runs out, Claude Code stops until the allowance resets. Knowing what draws on it is the difference between a limit that lasts the day and one that is gone by lunch.

Two windows at once

The allowance is measured in two rolling windows: a session window of about five hours and a weekly window. Every request counts against both at the same time. The status line exposes them as rate_limits.five_hour and rate_limits.seven_day, each with a used percentage and a reset time.

When a window runs out, you see a message with the reset time:

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am

The session and weekly limits are shared across all models. Switching from Opus to Sonnet with /model does not give you more room under either one. Some plans also have separate per-family limits (“You’ve hit your Opus limit”, “You’ve hit your Sonnet limit”). Those apply only to that model family, so switching to a model outside the family does keep you working, at the cost of a cold prompt cache: each model has its own cache, so the first request re-reads the whole conversation.

Because both windows fill together, one heavy burst of work, such as a large fan-out of parallel agents, can use up the weekly allowance before the session window even resets.

The docs do not publish the size of each plan’s allowance in tokens. You see percentages, not token counts.

Why it drains faster than you type

The model keeps no memory between requests, so every request carries the whole context window: the system prompt, CLAUDE.md, every earlier message and tool result. A tool call is another request with all of that plus the tool’s result. So a one-line question in a session that has been open all day costs the whole day’s conversation, even though most of it is read from the cache at a lower rate.

Other things draw on the allowance too:

• Cache misses. On a subscription the main conversation’s cache lives for an hour. Your first message after a longer break misses the cache and reprocesses the full context.
• Subagents and agent teams. Every subagent and teammate sends its own requests, which count against the same limits.
• Scheduled tasks and /loop. A scheduled task fires on its interval even when the session is idle, and each run sends the full context.
• Idle work. Messages from your other sessions and check-ins on an active goal start new turns while you are away, each sending the full context.
• Compaction. /compact reads the whole conversation to summarize it, so on a large context it is a large request. /clear costs nothing. Since 2.1.299, Claude Code also compacts on its own a conversation of 200K tokens or more that has sat idle for about 54 minutes. Turn that off with "idleCompaction": false in settings.json or the Idle compaction row in /config.
• Background requests. Summaries of past conversations for claude --resume and some status checks use a small amount, typically under $0.04 per session at API prices.

What a request costs also depends on what it carries: output, including the model’s thinking, is priced higher than input. See Tokens and Effort.

When you hit a limit

• A warning comes first. Before you hit the limit you may see something like You've used 85% of your session limit · resets 3:45pm.
• Claude Code can wait for you. Since v2.1.234, when a usage limit stops Claude mid-task in an interactive session signed in with a claude.ai subscription, Claude Code waits in the open session and continues the task after the reset. It does not start this wait on its own if the reset is more than 24 hours away (a weekly limit often is), in background sessions or -p runs, or with an API key. The wait ends without continuing if you send a prompt, exit, /clear or /resume. Cancel with Esc, start a wait yourself from /rate-limit-options, or turn it off in /config with Continue automatically at usage limit. The desktop app has its own, separate checkbox.
• Buy more. /usage-credits opens the usage-credits settings on Pro and Max, or asks your admin on Team and Enterprise. While you draw on usage credits, the main conversation’s cache lifetime drops from an hour to five minutes, so breaks get more expensive.

What to do about it

• Check where it goes with /usage before changing habits.
• Keep the context small and clear between tasks: see Managing context.
• Pick cheaper models and lower effort where they are enough: see Reducing token usage.

Gotchas

• /model does not reset a session or weekly limit. Only the per-family Opus and Sonnet limits care about the model.
• A subagent saves context, not allowance. Its requests count against the same limits.
• The 529 “Overloaded” error is not a usage limit. It is a capacity problem on the server side and does not count against your quota.
• Unattended retries. In the unattended retry mode, CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS (2.1.301) ends a request whose usage limit resets too far away instead of waiting for it.

Related

• /usage: see your limits and what used them.
• Tokens: input, output and cache, and what each costs.
• Effort: how much the model thinks, and why that costs output.
• Prompt caching: why a long pause makes the next message expensive.
• Statusline: keep both windows on screen.
• Reducing token usage: habits that make the allowance last.

Citations

1. Error reference: You’ve hit your session limit
2. Manage costs effectively
3. Interactive mode: wait for a usage limit to reset
4. Customize your status line
5. Changelog: 2.1.299, 2.1.301, 2.1.302