Claude Code limits: the 5-hour window, the weekly cap, and every path after the wall
Subscription limits are two clocks ticking at once: a 5-hour rolling window and a weekly cap. How they tick, why Opus burns the weekly pool first, what a 429 actually means, and the five ways past the wall — ranked by cost.
Limits have a way of not existing until the exact moment you are busy. They don't arrive with a monthly bill; they pick the moment you are half-way through a refactor, on a Friday, and turn your agent into a text box that only says 'try again later'. This post is not about bypassing limits — that is not a legitimate goal. It is about taking them apart: which clocks are ticking, what the machine is telling you when you hit the wall, and which exits actually exist, with the price of each printed on the door.
Disclosure up front: I operate Teapot Router, a usage-based API gateway for Claude Code. That gives me an obvious interest in one of the exits below — so the exits are ranked by how cheap they are, the free one comes first, and you can judge for yourself whether the ranking is honest.
Limits are two clocks, ticking at once
A Claude Code subscription limit is not one number, it is two: a 5-hour rolling window, and a weekly cap. The window starts when you start and resets five hours later; the weekly cap spans the whole week and accumulates whatever the windows don't forgive. The Tuesday-afternoon burst you just ran does not only occupy Tuesday's window — it draws down this week's pool.
So 'it just reset, why am I limited again' is usually not a bug. A full 5-hour window is one feeling; an exhausted weekly cap is another — and the second one means that even a freshly cleared window waits for the week to turn. /usage shows which clock you are actually standing against.
- The 5-hour window: rolling, decides whether you can keep going right now.
- The weekly cap: cumulative, decides how much week you have left.
- They meter independently — whichever fills first is the one that stops you.
Why Opus always burns the weekly cap first
The weekly cap meters usage, and a flagship model eats several times more usage per turn than a light one — longer context in, longer completions out. The same eight-hour heavy day drains the weekly pool several times faster on Opus than on Sonnet. Hence the famous asymmetry: a few days of Opus early in the week empties the weekly cap even while Sonnet-specific quota sits untouched — the pool is shared, and a specialty allowance does not refill the general tank.
This is not a punishment for heavy users; it is the pricing structure doing exactly what it says. A subscription is usage-capped insurance with a flat premium — the premium doesn't care which model you run, but the pool has a bottom. Once you see that, 'switch models' and 'switch billing' stop being folklore and become two variables in the same piece of arithmetic.
What actually happens at the wall
The surface symptom is a 429. It is not an error so much as the protocol telling the truth: quota spent, reset time in the response headers. Most clients will relay that reset time — so the first move at the wall is not switching tools, it is reading the clock and deciding how to spend the next hour.
Worth saying plainly: this wall exists on the subscription path. The usage-based API path has no 5-hour window and no weekly pool; its limits are a different species (per-minute throughput, tiered monthly spending ceilings) that a single developer coding alone essentially never meets. That does not make usage-based better — it trades the wall for a meter — but it is the fork where every exit below diverges.
Five exits, ranked by how cheap they are
The options after the wall have always been written down; they are just scattered across different documents. Collected and ordered by 'try the cheap one first':
- Wait for the reset. The 5-hour window turns over quickly and costs nothing. For the 'one last push' scenario: park the task, finish it after the window rolls.
- Compact the context. /compact, or start a fresh session. Every turn re-sends the conversation so far; trimming the dead weight makes each remaining turn cheaper. It doesn't restore quota, but it stretches what's left.
- Step down a model. Boilerplate edits and greps don't need the flagship; saving Opus for the genuinely hard asks slows the weekly burn immediately. The most underrated exit: most people's default model outclasses most of their tasks.
- Upgrade the plan. If your shape is hours a day concentrated on the flagship, the bigger pool genuinely is cheaper per unit of work — that is what tiers are for. Use them.
- Switch to usage-based. The wall disappears and the meter starts. It fits people whose usage is diverse, occasional, or spread across tools — and people who hit the wall more often than once a month, because blocked time is also a cost.
Which shape of person should stop where
The first four exits don't need this essay; anyone who has hit the wall once learns them. The place worth stopping to do arithmetic is between the fourth and the fifth: upgrade the plan, or switch to usage-based.
The raw material for that decision is your own usage shape: focused hours per day, task intensity, cache behavior. Feed them into a cost calculator and out comes the break-even — the hours per day at which usage-based spending catches the plan's price. Below that line, usage-based is cheaper; above it, the plan wins and the wall is the insurance premium you chose to pay. There is no universal answer, only your own multiplication.
One asymmetry worth knowing: a plan's price is locked, while usage-based rates follow the rate table. Anyone choosing the meter should demand a machine-readable price list and a per-request ledger — otherwise 'the meter is running' quietly becomes 'the meter is running in a locked box'.
Limits are not the enemy; they are the term of the contract your subscription signed: usage capped in exchange for monthly cost capped. The pain of the wall is the contract reminding you of its terms. You don't need to memorize five exits — you need to know your shape. Once the shape is clear, choosing where to stop is one-digit multiplication.
FAQ
How often do Claude Code limits reset?
The 5-hour rolling window resets five hours after it started; the weekly cap recovers on a weekly cadence. They are independent — a fresh window does not refill the weekly pool. When limited, check /usage to see which clock you're standing against.
Does the usage-based API path have limits too?
Yes, but a different species: requests-per-minute and token throughput (RPM/ITPM/OTPM) plus tiered monthly spending ceilings — not a 5-hour window or a weekly pool. For one developer coding, they're effectively invisible; they meter bursts and monthly totals, not sessions.
I got a 429. Is something broken?
No — 429 is the server reporting quota spent and when it resets, with the reset time in the response headers. Read the clock, then pick: wait out the window, compact context, or take one of the five exits above.