Set your own monthly spend limit below your provider's tier cap, add per workspace limits, and decide in advance what your app does when requests start failing. Limits protect the budget but also stop traffic, so pair them with alerts that fire well before the cap.
Three kinds of limit
The Claude rate limits documentation describes these:
- Tier spend cap. Each of the Start, Build, and Scale tiers has a monthly cap, and the Custom tier has none. The amounts are listed on the docs page and can change, so read the current table.
- Your own limit. You can set a limit below the tier cap on the billing page. You cannot exceed the cap.
- Workspace limits. You can cap spend per workspace, and also rate limits per workspace, set lower than the organization's. The default workspace cannot have limits set.
Organization wide limits always apply, even if workspace limits add up to more.
What failure looks like
The two cap types fail differently.
When you hit the tier cap, requests return HTTP 429 with a rate_limit_error type and an error code of enforced_spend_limit_reached. There is no retry-after header, and the docs say retries, including automatic SDK retries, fail until access resumes at 00:00 UTC on the first day of the next month unless you get a higher limit.
When you hit a limit you set yourself, requests return HTTP 400 with invalid_request_error, and the message says when access resumes.
If your error handling treats every 429 as a rate limit and retries, you will hammer a wall. Branch on the error code.
Plan the degraded mode
Decide before the incident:
- Which features keep working, if any, on a cheaper path.
- What users see: a clear message, not a spinner.
- Who gets paged, and who can raise the limit.
- Whether batch jobs pause first so interactive traffic survives.
Alert before the cap
The docs describe configuring alerts at thresholds when you set workspace spend limits. Use several, for example early in the month and again as spend approaches the limit, and send them to a channel a person watches. Add your own alert from the usage report, since reporting data typically appears within minutes.
Use separate workspaces for risky work
Put evaluations, backfills, and experiments in their own workspace with a low cap. A runaway script then exhausts its own limit, not production's.
Do not rely on limits alone
A limit tells you something went wrong after the money is spent. Per task budgets, loop caps in agents, and a pre-flight token count catch problems earlier.
Quick check
Should my retry logic retry a spend cap error?
No. The docs say that response has no retry-after header and retries fail until access resumes. Detect the error code and stop.
Can I set limits on the default workspace?
No. The docs say limits cannot be set on the default workspace, so use named workspaces for anything you want to cap.
Sources
Last reviewed: 19 October 2026.
