How does extra usage work with Claude: the eight-field rate_limit event behind the billing toggle

Extra usage is the overflow consumption path on paid Claude plans. Once your Pro or Max plan burns through its five-hour rolling cap or its seven-day weekly cap, any further messages are billed against a separate prepaid balance at standard Anthropic API rates. You toggle it on from Settings, Usage, Manage extra usage, set a monthly spending ceiling, and Claude stops treating "limit reached" as a hard stop. Under the hood your client, whether that is claude.ai, Claude Code, Cursor, or a third-party wrapper, sees a rate_limit event per turn with an isUsingOverage boolean that flips to true and an overageStatus that reads "allowed". If overage is off or the monthly ceiling is hit, the same event returns overageStatus "rejected" instead, and the next API call comes back as a 429 with an error message whose text contains the literal phrase "out of extra usage".

The full interface lives at acp-bridge/src/protocol.ts lines 244 to 256 in the Fazm repo. It is named RateLimitMessage and has eight fields: status (allowed, allowed_warning, rejected, unknown), resetsAt (Unix timestamp in seconds), rateLimitType (five_hour, seven_day, seven_day_opus, seven_day_sonnet, overage), utilization (0 to 1), overageStatus (allowed, rejected, or null), overageDisabledReason (string or null), isUsingOverage (boolean), surpassedThreshold (0 to 1, the warning threshold you crossed). The bridge forwards these from the Anthropic Agent SDK rate_limit_event stream verbatim. The human-readable labels are at Desktop/Sources/Providers/ChatProvider.swift lines 539 to 543: five_hour maps to "session limit", seven_day to "weekly limit", seven_day_opus to "Opus weekly limit", seven_day_sonnet to "Sonnet weekly limit", overage to "extra usage limit".

Fazm matches four distinct substrings in a single case-insensitive regex at acp-bridge/src/index.ts line 1903. The full pattern is /credit balance is too low|insufficient.*(credit|funds|balance)|you've hit your limit|you have hit your limit|hit your.*limit|rate.?limit.*rejected|out of extra usage|unable to verify.*membership/i. Each alternative catches a different real failure mode. "credit balance is too low" and "insufficient funds" fire on API-key accounts (Mode A) with no balance. "you've hit your limit" fires on Pro or Max accounts in the five-hour window with no extra usage enabled. "out of extra usage" fires specifically when overage was on but the monthly cap was hit. "unable to verify membership" fires when the OAuth token is stale. All four get the same credit_exhausted message type forwarded to the Swift UI at protocol.ts line 189, which is why Fazm can show one unified "usage limit" dialog regardless of which exact text Claude returned.

Anthropic counts two separate windows against your plan. The five-hour window is a rolling cap: every time you send a message, it opens a five-hour window, and your message counts against that window until it rolls off. The seven-day window is a fixed weekly cap measured from your plan renewal. Fazm forwards both types as the rateLimitType field and formats the reset time at ChatProvider.swift line 549 formatResetTime into a user-local "h:mm a" string. The bridge logs the reset time as a full ISO string at index.ts line 2464 so you can verify it from /tmp/fazm-dev.log. Practically, a five-hour rejection means "wait until 11:23 PM and try again". A seven-day rejection means "wait until next Tuesday or turn on extra usage".

The ACP subprocess is launched at acp-bridge/src/index.ts lines 517 to 542. Mode A is active when ANTHROPIC_API_KEY is set in the environment; Mode B is active when it is not, in which case the Claude Agent SDK authenticates via OAuth PKCE (acp-bridge/src/oauth-flow.ts lines 85 to 144) and charges against your Pro or Max plan. Line 535 logs which mode is active at startup: "Mode A (Fazm API key)" or "Mode B (Your Claude Account / OAuth)". ChatProvider.createBridge at Desktop/Sources/Providers/ChatProvider.swift lines 492 to 507 picks the mode based on the bridgeMode UserDefault. When Mode A runs out of credits or Mode B hits a weekly limit, the credit_exhausted message surfaces differently in the UI: Mode A suggests "switch to your personal Claude account in Settings" (ACPBridge.swift line 1605), Mode B suggests "upgrade to Claude Pro at claude.ai" (line 1603).

Yes. The rate_limit payload is stored in four @Published properties on ChatProvider at Desktop/Sources/Providers/ChatProvider.swift lines 378 to 384: rateLimitStatus, rateLimitResetsAt, rateLimitType, rateLimitUtilization. When status is "allowed_warning", Fazm logs the utilization percentage and fires an analytics event (ChatProvider.swift lines 522 to 525). When status is "rejected" at line 526, Fazm logs the formatted reset time and fires a distinct rejected event. The key branch is at ACPBridge.swift line 879: Fazm does NOT throw on a rejected rate_limit because the underlying API session may still complete (for example, a five-hour rejection that the SDK retries against overage). Only the actual API-level failure, which arrives as a credit_exhausted message with the "out of extra usage" text, produces the terminal "upgrade your plan" dialog.

Fazm maps HTTP status to errorType at acp-bridge/src/index.ts lines 1898 to 1902. A 402 or errorType === "billing_error" means the account ran out of credits (extra usage off or ceiling hit). A 429 or errorType === "rate_limit" means the five-hour or seven-day window was hit. Both get isStructuredCreditError === true, which short-circuits retries and surfaces the message immediately. The bridge also tracks invalid_request, authentication_failed, server_error, and image_error as separate errorType values (protocol.ts line 262). The api_retry handler at lines 2468 to 2478 records the httpStatus and errorType in the lastApiRetry module-level variable so the credit-exhaustion check can distinguish "server error, retry" from "billing problem, stop".

Because Anthropic returns both forms at different endpoints. The chat completions API uses the contraction; some Agent SDK paths unroll it to "you have hit your limit". Rather than assume the canonicalization is stable, Fazm matches both literally. The pattern also falls through to a third looser alternative, "hit your.*limit", which catches phrasing variations like "You have hit your weekly limit" or "hit your Opus weekly limit". This is defense in depth: if the structured api_retry event is missing or malformed for any reason, the regex still fires on the raw error message and the user still gets a credit_exhausted dialog instead of a generic error.

Every single Claude turn when you are on a paid plan. The SDK emits rate_limit_event as part of the streaming response before any content tokens arrive, carrying the current utilization and any threshold you just crossed. Fazm forwards all of them at index.ts line 2453 even when status is "allowed" so the Swift app can keep its progress indicators live. A typical log line from /tmp/fazm-dev.log looks like "Rate limit: status=allowed, type=five_hour, utilization=0.42, resets=2026-04-20T16:00:00.000Z". When you cross 80 percent, you start seeing status=allowed_warning. When you cross 100 percent with overage off you see status=rejected with overageStatus=rejected and the next request fails.

Yes. Fazm writes to /tmp/fazm-dev.log for development builds and /tmp/fazm.log for production. After any chat turn, tail the log and grep for "Rate limit" or "Credit/rate limit exhausted". You will see the exact structured event and the detection method (structured httpStatus=429, errorType=rate_limit vs regex) logged verbatim at index.ts lines 1905 to 1908. This is the audit trail: if a Claude message ends in an upgrade-plan dialog, the log will tell you whether the trigger was a 402 billing_error, a 429 rate_limit, or a string match on "out of extra usage" in a 500 response body.

No, and the difference matters. claude.ai draws from your plan first, then dips into extra usage if enabled. Third-party API clients (Claude Code, Cursor, Windsurf, Fazm in Mode B) share the same plan balance but different apps apply different retry policies. Fazm's specific retry policy is in acp-bridge/src/index.ts lines 1963 to 2000: if errorType is billing_error, rate_limit, or invalid_request, Fazm does NOT retry. It surfaces the error as credit_exhausted and the user sees the reset time plus an Upgrade to Pro link. Other wrappers aggressively retry through the 5-hour window, which burns more of your extra-usage balance than you might expect. Check each wrapper's retry code before you enable auto-reload on extra usage.

You do not do it from Fazm directly. Extra usage is a plan-level setting managed at claude.ai, Settings, Usage, Manage extra usage. Fazm uses whichever plan mode you have (OAuth Mode B) or its built-in API key (Mode A). To stop Fazm from ever touching extra usage, either turn off the toggle at claude.ai or switch bridgeMode to builtin in Fazm Settings to use the bundled API key that bills independently. The bridgeMode logic is at ChatProvider.swift lines 492 to 507 and persists across app restarts. The ACP subprocess is torn down and restarted with a different environment when you flip it (line 558 comment confirms the deferred switch during in-flight queries).