A 429 is a failure mode dressed up as a status code. By the time your client reads it, the request has already been spent. The turn that was mid-flight is gone. The agent's reasoning chain is broken. Whatever Claude Code was about to do, it is now doing something else — sleeping Retry-After seconds, then starting cold.
That is the design problem most clients solve wrong. They catch the 429, sleep, and retry. The catch happens too late. The interruption has already been recorded against the active conversation, and the wall-clock cost of the recovery — re-establishing context, re-reading files, re-discovering conclusions — is the thing that actually hurts.
Power Claude rotates before the 429. This is an engineering essay on why that is the right design and how the proxy makes it work.
The 429 is a post-mortem, not a warning
Reactive rotation reads like a reasonable defense if you have not thought about it for long: catch the exception, sleep the window, switch accounts on the retry. Three lines of code, problem solved.
The problem with that design is the cost of the failure path. A 429 from api.anthropic.com is not free. It consumes the request slot that produced it. Anthropic's own behavior — confirmed in their public rate-limit documentation and observable on any over-quota account — is that a 429 counts against your bucket. You spent the call to learn the call would have failed.
For a single-turn API client, that wastes one request. For Claude Code, it wastes a turn inside a live conversation:
- The agent's queued tool calls beyond the failed turn never run.
- Whatever in-memory plan the model was building for the next two or three steps is gone.
- The session resumes from the last successfully-completed turn — which may be several reasoning steps behind where the agent actually was when the call failed.
- The retry burns another
Retry-Afterwindow of wall-clock time you were not expecting to spend.
Reactive rotation papers over the first issue (the failed request) and ignores the rest. Pre-emptive rotation eliminates all four.
What Anthropic sends on every successful response
The anthropic-ratelimit-* headers are the load-bearing data structure for this design. They are included on every API response, not just on failures, and they expose the full rate-limit state in advance:
anthropic-ratelimit-requests-limit: 50
anthropic-ratelimit-requests-remaining: 38
anthropic-ratelimit-requests-reset: 2026-05-27T14:23:00Z
anthropic-ratelimit-tokens-limit: 40000
anthropic-ratelimit-tokens-remaining: 12847
anthropic-ratelimit-tokens-reset: 2026-05-27T14:23:00Z
anthropic-ratelimit-input-tokens-limit: 30000
anthropic-ratelimit-input-tokens-remaining: 8422
anthropic-ratelimit-input-tokens-reset: 2026-05-27T14:23:00Z
anthropic-ratelimit-output-tokens-limit: 16000
anthropic-ratelimit-output-tokens-remaining: 4102
anthropic-ratelimit-output-tokens-reset: 2026-05-27T14:23:00ZFour limit dimensions are exposed: requests-per-minute (RPM), total tokens-per-minute (TPM), input tokens, and output tokens. Each carries a limit, a remaining, and a reset ISO timestamp. Every successful 200 you ever get from the API carries this full set.
This is everything pre-emptive rotation needs. The decision to switch accounts can be made on the response that just succeeded — before the next request goes out, before any 429 is possible.
The five-hour and seven-day window state is not in these headers; those windows are tracked separately and surface through the heartbeat and the proxy's per-account ledger. @CONFIRM-FACT: per-minute headers are the canonical pre-emptive signal; long-window state in Power Claude is derived from the per-minute history plus the reset timestamps.
The decision loop
The proxy runs the same loop on every response. It is deliberately simple — complexity in this layer is what creates ping-pong, spurious rotation, and missed signals.
- Parse the unified headers. Extract all four dimensions, the remaining counts, and the reset timestamps from the response.
- Compute per-dimension utilization.
utilization = 1 - (remaining / limit). Track these in a rolling per-account ledger. - Threshold check. If any dimension is below its rotation threshold — the threshold is a fraction of the limit, not zero — flag the account as
approaching. - Select the next account. The account selector picks from healthy accounts in the pool. Balanced Mode picks the lowest-utilization account across dimensions; the standard rotator falls through to the next healthy one.
- Route the next request. The proxy rewrites its upstream target so the subsequent call goes to the new account. The Claude Code session continues uninterrupted on the same OAuth credential, which Power Claude rewrites at
~/.claude/.credentials.jsonbetween requests. - The 429 never fires. The approaching account has been retired from the active pool before its remaining capacity hits zero. Its reset window will clear before the selector picks it again.
Threshold values are not zero, and not the obvious "rotate at 10% remaining" either. The threshold has to leave room for in-flight requests already on the wire, for token-count estimates that may be wrong, and for the model occasionally returning a longer response than its input would predict. @CONFIRM-FACT: the v0.15+ proxy's exact threshold constants are an implementation detail and not part of the public contract — they are tuned against the headers, not configured by users.
The whole loop is sub-millisecond. It runs inside the local proxy process, on the same machine as your editor.
Why this only works in a proxy
You cannot pre-emptively rotate from inside Claude Code itself. The CLI does not expose a hook that fires on "successful response, before next request." It only exposes a Stop hook that fires after the model is done, which is too coarse — by then several requests have come and gone and the rate-limit state has moved underneath you.
A proxy gets all of it. It sees the full response headers on every call, in order, with no rate of sampling. It can update the account ledger and rewrite the upstream target between any two requests without Claude Code being involved.
The Power Claude proxy is a local Node process that listens on localhost. Claude Code is configured (via ANTHROPIC_BASE_URL for that one process) to send its API traffic through it. The proxy then forwards to api.anthropic.com directly. No cloud middleman, no shared service, no third-party visibility — the traffic path is:
Claude Code → localhost:PROXY_PORT → api.anthropic.comNot:
Claude Code → localhost:PROXY_PORT → some Neural-LLM server → api.anthropic.comThe proxy's job is exactly two things: read the rate-limit headers on every response, and choose which account credential to attach to the next request. Both happen on your machine. (For the broader question of what data leaves your box, see pre-emptive rotation and the privacy walkthrough.)
Power Mode: pre-emptive at every step, not just at the wall
Standard rotation reads "exhaust one account, switch to the next." That is a single-account ceiling with a graceful failover. Power Mode is a different posture: route every request to the least-busy account at the moment of the request, so all accounts in the pool drain together instead of one at a time.
In Power Mode, the threshold logic above still runs, but the account selector also weighs current in-flight count and recent burn rate. The practical effect with three accounts in the pool is that you get an effective ~3× per-minute ceiling on TPM, RPM, input TPM, and output TPM simultaneously. Heavy Opus sessions that used to stall every thirty minutes run uninterrupted, and the per-minute throttling that can choke sub-agent fan-out simply stops mattering. (Five accounts in Balanced Mode is what /pricing is built around — five Pro at ~$100/mo for the same per-minute ceiling as a single Max at $200/mo, with five independent reset windows.)
The cumulative claim Power Claude tracks for Balanced Mode in the dashboard is N throttle waits avoided — the count of times the smart-429 router successfully routed around a throttle instead of waiting the Retry-After. That number sits next to the active-mode indicator so you can see the multiplier doing its job. (The deeper telemetry tour is in the dashboard walkthrough — see /changelog for the v0.10.1 dashboard introduction.)
Smart 429 routing: the fallback path
Pre-emptive rotation reduces 429s to a rare event, but rare is not zero. Network races happen. Burst traffic that exceeds the threshold buffer happens. Anthropic sometimes throttles a per-minute window faster than the previous response's headers predicted, particularly on input-token-heavy turns.
When a 429 does arrive, the proxy treats it as the fallback path:
- The throttled account is put in cooldown for its
Retry-Afterwindow — not the proxy's heuristic, the server's authoritative cooldown. - The selector picks the next healthy account and the request is retried.
- The cooldown is structural: the selector cannot pick the throttled account again until the server-issued window clears. This prevents the ping-pong failure where two throttled accounts bounce a request back and forth.
- If the entire pool is throttled at the same time — every account in cooldown simultaneously — the proxy falls back to the wait-and-retry path on the least-bad account. You never end up worse off than a single-account client.
Power Claude logs each one of these events in ~/.power-claude/logs/handler.jsonl so the dashboard can count "throttle waits avoided." That number tends to be small in steady state because pre-emptive rotation prevents most of them; the count rises during sustained heavy use when threshold bursts overshoot.
What you actually see
From inside Claude Code, the rotation is invisible. The status-bar chip might update — Power Claude shows the active account name there — but the conversation thread, the file context, the agent's plan, all of it persists across the rotation. The session itself is durable because the agent state lives in the JSONL transcript and the working tree, not in the API connection.
The pre-emptive rotation is announced in the Power Claude status bar before it happens (⚡ Balanced [3] ~3× while active, with rotation events scrolling) and recorded in the event log for later inspection. If you want to see what just happened, pc logs -f --level info tails the stream. If you want the post-hoc graph, the Insight Graph annotates each rotation as a marker on the session lane.
What you do not see is the 429. That is the entire point.
The minimum viable account pool
One account cannot pre-emptively rotate, because there is nothing to rotate to. The proxy still observes the headers and warns you when you are approaching the wall (the Runout Forecaster banner — see pre-emptive rotation for the recovery flow when the wall hits anyway), but the savings come from having a second healthy account ready to take over.
Two accounts is the inflection point. Three is where Balanced Mode starts paying for itself. Five is the configuration the /pricing page is built around: five Pro at $100/mo gives you the same per-minute ceiling as one Max at $200/mo, plus five times the per-minute headroom because every account has its own independent window.
Adding accounts beyond five hits diminishing returns — at some point the bottleneck is your typing speed, not Anthropic's rate-limit windows. For heavy sub-agent fan-out workflows the marginal value of a sixth or seventh account is still positive, but the curve flattens fast.
Why this is the only design that preserves session continuity
The deeper reason pre-emptive rotation matters has nothing to do with the 429 itself. It is about what does and does not survive a rotation.
When a session is interrupted by a 429, what survives is the JSONL transcript on disk and the working tree. What does not survive is the agent's working memory of where it was — the queued tool calls beyond the failed turn, the half-formed plan it was three steps into, the file it had just read but not yet acted on. Those exist only in the message thread, and the message thread is interrupted at the failed turn.
When pre-emptive rotation switches accounts mid-stream, none of that is lost. The next request goes through cleanly. The agent never sees a failure. The session keeps its working memory because there is no break to recover from.
This is the difference between "rate limits handled" and "rate limits invisible." Reactive rotation handles them. Pre-emptive rotation makes them invisible. They are not the same thing.
Download Power Claude to see your pool's rotation behavior on your next long session, or read the getting-started guide for the activation flow.
Quick Reference
Q: Why is catching a 429 the wrong approach? A: A 429 means the request was already spent. The agent's reasoning chain in Claude Code is interrupted at that turn, and the Retry-After window adds wall-clock time you did not budget. The cheapest 429 is the one that never fires.
Q: How does pre-emptive rotation actually work? A: Every successful API response carries anthropic-ratelimit-* headers showing remaining capacity across four dimensions (requests, tokens, input tokens, output tokens). The proxy reads them, computes utilization, and rotates to a healthier account before any dimension reaches the limit. The 429 never fires.
Q: Why does this need a proxy? A: Claude Code does not expose a hook that fires "between requests on response headers." Only a proxy sits in that position. The proxy is a local Node process — no cloud middleman, no third-party server in the traffic path.
Q: Is there still a fallback if a 429 sneaks through? A: Yes. The smart-429 router cools the throttled account for its Retry-After window (server-issued, not heuristic), picks the next healthy account, and retries. Ping-pong is structurally impossible — a cooled account cannot be re-selected until the server says it is ready.
Q: How many accounts do I need for this to matter? A: Two is the minimum (pre-emptive rotation needs somewhere to rotate to). Three unlocks Balanced Mode's ~3× per-minute ceiling. Five accounts at ~$100/mo total gives you the same Opus ceiling as a single Max account at $200/mo, with five independent reset windows running in parallel.
Q: Does the agent know it rotated? A: No. The conversation thread, the tool-call plan, the working memory — all of it persists because the rotation happens in the proxy between requests, with no break for the agent to observe.
Q: What does the cumulative "throttle waits avoided" number mean? A: Each time the smart-429 router catches a 429 and routes around it instead of sleeping Retry-After, the counter increments. A high number on a heavy day means the smart-429 router did real work; on a quiet day it stays close to zero because pre-emptive rotation prevented the throttles upstream.
Q: Where can I see this in action? A: The Power Claude dashboard shows the active mode, the per-account utilization bars, the Runout Forecaster banner, and the cumulative "throttle waits avoided" counter. pc logs -f --level info from the CLI gives the same stream as it happens.