Claude billing banner, read from the Fazm source
"Third-party apps now draw from your extra usage, not your plan limits. Add more at claude.ai/settings/usage and keep going."
Anthropic shows that banner the instant your Claude subscription plan quota is exhausted. Every existing answer to this phrase stops at "go add credit and click retry." This page is about the part those answers skip: the eight-field rate_limit event the SDK emits at the same moment, which fields most third-party clients drop on the floor, and what a persistent-session Mac agent does with the boolean that drives the banner.
Direct answer (verified 2026-05-17)
What the banner means
It is an informational banner, not an error. Your Claude subscription's plan quota (the five-hour session cap or the seven-day weekly cap) just filled up. Until it refills, any third-party app authenticated against your Claude account (Claude Code, Cursor, Windsurf, Zed, a custom ACP client, Fazm, anything OAuth-based) is now billing against your prepaid extra-usage credit balance instead of your plan.
Your agent keeps working. To check or add credit, go to claude.ai/settings/usage. When the extra-usage balance also runs to zero you start seeing a different message: out of extra usage. That one IS a hard rejection. This one is not.
Authoritative source: Anthropic's Use Claude Code with your Pro or Max plan.
If you just want to act on the banner
The short path. Everything below this is about the wire-protocol shape the banner is generated from, which is the actually interesting part if you build or use a third-party Claude client.
Six-step fix
- Open claude.ai/settings/usage in your browser.
- Sign in with the same Claude account your third-party app uses.
- Check the "Extra usage" balance card. Positive number means tools keep working.
- If the balance is at zero, click "Add extra usage" and load $10 or $20.
- Enable auto-reload if you use third-party tools daily, so the balance never lands on zero mid-flow.
- Retry the request in your third-party app. The same banner stays visible, but tools resume.
What the existing answers leave out
Every public answer for this phrase, including Anthropic's own help page, lands on the same script: explain that the plan filled, point at claude.ai/settings/usage, tell the user to add credit. That is correct as far as it goes. It just stops well before the interesting part of the story.
The client-side gap
- Anthropic's help center calls the banner informational and tells you to go to claude.ai/settings/usage. It does not describe the rate_limit event behind it.
- Anthropic's API reference documents the rate_limit_event SDK callback but does not show how a third-party client should surface the isUsingOverage boolean to a human.
- Existing guides on "why does my Cursor request say request rejected" cover the failure case (overage exhausted) but skip the warning case (overage just started).
- Existing guides assume a stateless client. None describe what happens to an in-flight persistent session when the boolean flips mid-tool-call.
- No top-ranked answer cites the field-by-field shape of the event. Most just paraphrase the banner text.
- No top-ranked answer separates the four lifecycle states: plan-only, plan-warning, overage-active, overage-exhausted.
The anchor fact
The rate_limit event behind the banner carries eight fields. Fazm forwards every one.
The event is emitted by Anthropic's Agent SDK over the same streaming channel that delivers assistant text and tool calls. Most third-party clients consume status and resetsAt and ignore the rest. Fazm's Node bridge at acp-bridge/src/index.ts lines 4457-4480 destructures all eight and forwards them with sendWithSession. The Swift parser at ACPBridge.swift:1497-1504 constructs a strongly-typed .rateLimit enum case. The handler at ChatProvider.swift:865-898 updates four published properties and maps rateLimitType: "overage" to the user-facing label "extra usage limit" at line 895.
The eight fields, what each one carries
These are the field names as they arrive on the wire and as Fazm re-emits them downstream. Same names, same types. The one that drives the banner you searched is isUsingOverage.
status
One of "allowed", "allowed_warning", "rejected", or "unknown". When the banner fires, status is typically "allowed_warning".
resetsAt
Unix timestamp in seconds. When the plan limit you just hit will refill. Used to format the "resets in 3 hours" copy in the UI.
rateLimitType
The machine code for which limit fired: five_hour, seven_day, seven_day_opus, seven_day_sonnet, or overage. ChatProvider.swift:889 maps it to a human label.
utilization
A float from 0 to 1 showing how much of the limit you have used. At the threshold-crossing moment this is at or above 1.0.
overageStatus
Whether extra usage is allowed ("allowed"), denied ("rejected"), or absent (null). "rejected" is when the next request will fail with HTTP 402.
overageDisabledReason
If overageStatus is rejected, the reason: "monthly_cap_reached", "overage_disabled_by_admin", or a similar string. null otherwise.
isUsingOverage
Boolean. true means the current request is being billed against the extra-usage pool, not the plan. This is the boolean the banner is generated from.
surpassedThreshold
Float warning threshold you crossed (0.6, 0.85, 1.0). Lets a UI render a graduated warning before the plan cap fills, not just at the moment it fills.
Four lifecycle states, one event stream
The banner you searched fires at state three. State four is the harder rejection that catches people off guard, and it gets the bulk of the existing public guidance. State two is where a thoughtful UI can warn you before you ever see state three.
Plan only
isUsingOverage false, status allowed, rateLimitType is one of the plan limits. Direct usage on the plan, nothing unusual on the wire.
Plan warning
status allowed_warning, surpassedThreshold around 0.85. The SDK is warning you that the cap is about to fill. No banner yet.
- 3
Overage active
isUsingOverage true, status allowed_warning, overageStatus allowed. The banner appears. Third-party apps now draw from extra usage. This is the state the keyword names.
- 4
Overage exhausted
status rejected, overageStatus rejected, the next request fails. Error message contains "out of extra usage". Fazm's classifier at api-failure.ts:34 surfaces this as a credit_exhausted session message.
What happens in a Fazm window the moment the banner appears
Four frames, top to bottom, from a normal mid-conversation to the banner being visible to the user. The session stays open the whole time.
Frame 1 — Long agent run, mid-conversation
A Fazm window has been running for an hour. The persistent session is alive, the chat history is intact, the model is mid-tool-call. The five-hour plan cap is about to fill.
The five-step trip from event to banner
A more deliberate version of the same trip, written as documentation a peer building a third-party Claude client could follow.
- 1
Plan cap fills
Your Claude Pro or Max plan has a five-hour rolling session cap and a seven-day weekly cap. The session cap fills first on a long agent run.
- 2
SDK emits rate_limit_event
Anthropic's Agent SDK fires a rate_limit_event over the streaming connection with eight fields. status flips to allowed_warning, isUsingOverage flips to true, surpassedThreshold reports the threshold you crossed (typically 1.0).
- 3
ACP bridge forwards every field
Fazm's Node bridge at acp-bridge/src/index.ts lines 4457-4480 destructures all eight fields and forwards them with sendWithSession. No truncation, no normalization, no dropped booleans.
- 4
Swift parses and routes
ACPBridge.swift lines 1497-1504 reads the JSON dict and constructs a .rateLimit enum case. ChatProvider.swift handleRateLimitEvent at line 865 updates four published properties and logs the warning.
- 5
Banner renders, session continues
The UI shows the human label (overage -> "extra usage limit") and the next tool call goes out on the extra-usage pool. The session itself does not close. The on-disk transcript keeps growing.
Before and after: what a thin client loses
The thin-client behavior on the left is the default in most ACP-flavored wrappers. Toggle to the persistent-session behavior on the right.
The bridge sees the rate_limit event but only forwards status and resetsAt. The UI shows a generic warning. isUsingOverage and surpassedThreshold are dropped. If the chat is mid-tool-call, the client may reconnect, which restarts the session, which loses the in-memory context.
- Drops six of eight fields
- Generic warning, not tied to the actual event
- Session may reconnect on warning
- In-memory context lost on reconnect
- User cannot fork the chat at this moment
Persistent-session client vs the default behavior at this moment
What changes when a client treats the rate_limit event as a first-class session update instead of a one-off warning to render.
| Feature | Typical wrapper | Fazm |
|---|---|---|
| Where the eight rate_limit fields are exposed | Most clients consume only status and resetsAt, drop overageStatus, overageDisabledReason, isUsingOverage, surpassedThreshold. | Every field forwarded as a session_update message at acp-bridge/src/index.ts:4467, parsed into a strongly-typed enum case at ACPBridge.swift:1497-1504. |
| What happens to the in-flight session | Varies. CLI wrappers typically print the warning and continue. Browser-based clients sometimes force a page reload on the warning. Stateless wrappers lose any cached context. | The session stays alive. ACP keeps the connection. The on-disk transcript at ~/.claude/projects/<encoded(cwd)>/<sessionId>.jsonl keeps growing. The next tool call lands on the extra-usage pool with no reconnect. |
| Banner copy | Hard-coded variants of Anthropic's banner string. No tie to the actual emitted event fields. | Rendered from the rateLimitType mapping at ChatProvider.swift:895 ("extra usage limit") plus the resetsAt timestamp formatted by formatResetTime(_:). |
| Forking the chat at this moment | No fork. Restarting the chat loses the conversation; copy-pasting context costs more tokens than it saves. | One-click fork button on every Fazm window opens a new chat with the full prior context. Original window is untouched. Both windows continue on the extra-usage pool. |
| Auto-compacting | Many wrappers silently compact context at session boundaries. The plan-cap event can coincide with a compaction the user did not ask for. | None. Full history stays in context for the window's lifetime. The plan-cap moment does not trigger a context truncation. |
| Voice continuation | Voice-first wrappers are rare and typically do not preserve session state across the plan-cap transition. | Hold the hotkey, keep talking. The voice path uses the same persistent session, lands on the extra-usage pool with no extra setup. |
Wrappers vary widely. This is the common case, not a universal claim. If your client preserves every field and keeps the session alive, it is closer to the left column.
Verify the anchor facts yourself
The line numbers on this page came from the Fazm repository on main, checked out on 2026-05-17. Reproduce them with the commands below.
The same banner across the ACP ecosystem
The Agent Client Protocol is a shared transport. The same rate_limit event reaches every ACP-flavored client. What differs is how much of the event each one keeps.
Claude Code CLI
Prints a status line at the warning, continues. Does not surface the boolean. No persistent UI to fork from.
Codex (codex-acp)
ACP-compatible. Fazm bundles codex-acp as a swappable backend per chat. Same event shape, separate billing track on OpenAI.
Zed
Editor-integrated ACP. Shows the warning in the bottom bar. Does not preserve a session across an editor restart.
Cursor
Not ACP. Bring-your-own-Pro flow billed against the same extra-usage pool. Banner shown as a one-off toast.
Custom ACP client
If you wire @agentclientprotocol/claude-agent-acp directly, you get the full rate_limit_event. Whether you surface it cleanly is up to your bridge.
Fazm (this page)
Forwards all eight fields, persists the session across the warning, one-click fork on every window, no auto-compacting.
Want this rate_limit-event handling in your own Claude client?
20 minutes. I will walk through the eight-field destructure, the Swift parser, and the persistent-session handoff so you can lift the pattern into whatever ACP bridge you are building.
Adjacent topics on Claude extra usage and persistent sessions
Related guides on this site
How extra usage works with Claude (the eight-field rate_limit event)
Deeper on the protocol: what every field carries, how the SDK ships them, and where each one is consumed in a real client.
Make your $20 Claude extra usage credit last on third-party apps
Token economics: why screenshot-based agents burn through the prepaid balance faster than accessibility-tree agents.
Your org is out of extra usage for the month: a fallback pattern
What happens after the extra-usage pool is fully drained, and how a built-in fallback pool can keep an agent loop alive.
Frequently asked questions about the extra-usage banner
What does the banner "third-party apps now draw from your extra usage, not your plan limits" actually mean?
It is an informational banner Anthropic shows when your Claude subscription's plan quota (the five-hour session cap or the seven-day weekly cap) is exhausted. Once the cap is hit, any third-party app you connected to your Claude account (Claude Code, Cursor, Windsurf, Zed, a custom ACP client, Fazm, anything OAuth-based) stops drawing from the plan and starts drawing from your prepaid extra-usage credit balance. Your direct usage on claude.ai still draws from the plan first. The banner is not an error. Your tools keep working as long as you have credit in the extra-usage pool. When that pool runs out you start seeing the harder "out of extra usage" rejection instead.
What is actually shipped on the wire when this banner appears?
Anthropic's Agent SDK emits a rate_limit_event with eight fields: status ("allowed", "allowed_warning", or "rejected"), resetsAt (Unix timestamp), rateLimitType ("five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet", or "overage"), utilization (0 to 1), overageStatus ("allowed", "rejected", or null), overageDisabledReason (string or null), isUsingOverage (boolean), and surpassedThreshold (the warning threshold you crossed). At the moment the banner appears, status is typically "allowed_warning", rateLimitType is one of the plan limits, and isUsingOverage flips to true. The banner text is generated client-side from that boolean. Fazm extracts all eight fields at acp-bridge/src/index.ts:4457-4480, parses them on the Swift side at ACPBridge.swift:1497-1504, and feeds them into the ChatProvider published state.
Do I need to do anything when I see the banner?
Not immediately. The banner is telling you a billing pool switched, not that anything is broken. If you have credit in your extra-usage balance, every tool call your third-party app makes will go through as usual. If the extra-usage balance is empty, the next request fails with an HTTP 402 billing_error and the message body contains the literal phrase "out of extra usage". The action is the same in both cases though: open claude.ai/settings/usage, check your extra-usage balance, and add credit if you want third-party apps to keep working past the plan cap. The plan limits themselves reset on their own schedule (every five hours for the session cap, every seven days for the weekly cap).
Why does the banner specifically call out third-party apps?
Because the rule it announces only applies to them. Direct usage on claude.ai and the Claude Desktop app always tries the plan first and only falls back to extra usage when the plan is empty. Third-party apps that authenticate via your Claude account (the OAuth-based bring-your-own-Pro flow) always draw from extra usage once the plan is full, never from the plan itself. The banner is Anthropic separating the two billing tracks visibly so a user who watches their claude.ai chat keep working does not assume their Cursor session will too.
Where can I see the eight-field rate_limit event in Fazm's source?
Three files. /Users/matthewdi/fazm/acp-bridge/src/index.ts:4457-4480 is the Node-side handler that destructures all eight fields off the ACP message and forwards them with sendWithSession to the Swift side. /Users/matthewdi/fazm/Desktop/Sources/Chat/ACPBridge.swift:1497-1504 is the Swift parser that pulls overageStatus and overageDisabledReason out of the JSON dict and constructs an .rateLimit enum case. /Users/matthewdi/fazm/Desktop/Sources/Providers/ChatProvider.swift:865-898 is the handler that updates the published rateLimitStatus, rateLimitResetsAt, rateLimitType, rateLimitUtilization state and maps the machine string "overage" to the human UI label "extra usage limit" at line 895.
How does this state interact with a persistent session?
It does not interrupt it. The whole point of forwarding the rate_limit event as a session_update is that the session itself stays alive. The Claude Agent SDK keeps the connection open, the on-disk transcript in ~/.claude/projects/ keeps growing, and the next tool call in the same session lands on whichever pool now has budget. In Fazm specifically, a chat window that hits this banner mid-conversation does not close, does not need re-auth, and does not lose context. If you fork the chat at this point (the one-click fork button on every Fazm window) the new window inherits the full prior context and runs on the same pool until the user decides otherwise.
What is the difference between "allowed_warning" with isUsingOverage true, and "rejected"?
Two different points in the lifecycle. allowed_warning + isUsingOverage true is the state the banner describes: you have crossed into overage and you are spending from the extra-usage credit pool. status is "allowed" because the request is going through. rejected fires when the extra-usage pool is also empty or overage is disabled (overageStatus comes back as "rejected" with an overageDisabledReason). At that point the API call comes back with HTTP 402 or 429 and the error message contains "out of extra usage". Fazm's classifier at acp-bridge/src/api-failure.ts:34-59 distinguishes the two on the structured fields (errorType, httpStatus) and surfaces them to the UI through separate session messages.
Does this banner affect my API key billing?
No. The OAuth-based extra-usage track is one of three separate billing concepts. Plan limits cover claude.ai and the mobile app, included with your Pro or Max subscription. Extra usage is the prepaid credit balance that third-party apps draw from once the plan is hit (this is what the banner is about). Direct API billing on a raw API key is a completely separate track with pay-per-token invoicing, and the banner has nothing to say about it. If your tool is configured with an Anthropic API key instead of OAuth, the rate_limit event still fires from the SDK but the overage bucket is irrelevant because the API key bills directly.
Can I verify these line numbers myself?
Yes. Clone the repository at github.com/mediar-ai/fazm and run these from the repo root. grep -n 'isUsingOverage' acp-bridge/src/index.ts returns lines 4465, 4475 and the corresponding Desktop/Sources/Chat/ACPBridge.swift references. sed -n '4457,4480p' acp-bridge/src/index.ts prints the full eight-field destructuring block. sed -n '889,898p' Desktop/Sources/Providers/ChatProvider.swift prints the rateLimitTypeLabel(_:) helper with the overage-to-extra-usage-limit mapping. All references verified on main on 2026-05-17.
Comments (••)
Leave a comment to see what others are saying.Public and anonymous. No signup.