Claude Code spend limit per developer: what it caps
Anthropic's Claude apps gateway can cap each developer's spend by day, week or month, per user, per identity-provider group or for the whole organization. At the cap the gateway returns 429. The caps are USD estimates, fail open by default if Postgres is down, and bind a person, not an agent. They also do not cover a developer who calls the provider directly.
The gateway caps a person, and you set the cap through an API
The Claude apps gateway is Anthropic's own self-hosted gateway for Claude Code, built into the claude binary. Its spend-limits page (read on 19 November 2026) describes the control: caps "by day, week, or month", set with an admin API and enforced "live on every request".
Caps are not written in gateway.yaml. Each POST /v1/organizations/spend_limits creates or replaces one cap from a scope, an amount and a period. This request sets an organization-wide default of $500 a month, copied from the page:
curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
-H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
-H "Content-Type: application/json" \
-d '{"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}'
The amount is a whole-number string of USD cents, so "50000" is $500. The documented scopes are three:
scope.type | Targets |
|---|---|
user | One developer, by the OpenID Connect sub the identity provider assigns |
rbac_group | An identity-provider group, by name |
organization | The org-wide default |
A group or organization cap "is a per-seat default that each member inherits, not a shared pool". Per period, the effective cap resolves in this order: a per-user override, then the most restrictive of the developer's group caps, then the org default, then unlimited. A scope can hold one cap per period, and "a developer is blocked if over any of them".
For a team that gives Claude Code to engineers through one shared cloud credential, this is the right shape. The provider's bill shows one credential. The gateway adds a per-person view on top, with SSO sign-in, group rules and warnings in the client at 75% and 95% of a cap.
At the limit the request is refused with a 429
On each /v1/messages request the gateway looks up the caps and period-to-date spend in one Postgres query. A developer over any cap gets 429 with error.type: billing_error and the header x-should-retry: false. The message for a cap above zero carries the UTC reset date, plus an optional admin.blocked_message such as a link to request an increase:
spend limit reached · resets Dec 1 · request an increase at https://go.example.com/claude-limits
Two details matter for anyone who has run a retry loop. The x-should-retry: false header is a signal to clients not to retry. And a cap of "0" "blocks every request", with no reset date, so it works as a manual stop for one person or group.
Caps reset on UTC calendar boundaries: daily at 00:00 UTC, weekly on Monday, monthly on the first. Token counting is never blocked, "because token counting is free".
The block happens before the upstream call. That is what makes a cap a limit rather than an alert. The daily spending limit guide compares how provider-side limits and LiteLLM budgets reset.
The meter is an estimate, and unknown models are billed, not free
After each response a usage meter reads token counts and adds the cost to the daily, weekly and monthly counters. The amounts are, in the page's words, "USD estimates, a circuit breaker rather than an invoice". Rates come from a documented order:
- A matching
pricing.overridesrow for the upstream that served the request. - List price for the upstream model ID, when Claude Code's cost table recognizes it.
- List price for the
models[].idyou mapped to that upstream ID. - "The unknown-model tier of $5/$25 per million input/output tokens, so an ID the meter can't place is never free."
Two choices here are worth copying. An unknown model is billed at a flat rate instead of at zero. And client aborts are billed too: "When a stream ends without the upstream's final usage frame, the meter bills a floor estimate of about four characters per output token for the text already sent to the client, so aborting requests early doesn't evade a cap."
The limit is that this is still an estimate. A flat $5/$25 tier can overstate a cheap model and understate an expensive one. The page tells you to reconcile against the provider's own usage reporting for billing, and pricing.overrides rows exist so you can enter contracted rates.
It fails open by default
The pre-check queries Postgres with a two-second timeout. The page states what happens when that fails:
If the store is unreachable or times out, enforcement fails open by default: the request proceeds, the gateway logs a warning, and the response carries no
anthropic-ratelimit-unified-*headers.
The configuration reference documents the switch, enforcement.fail_closed_on_error, default false:
enforcement:
fail_closed_on_error: true # requires an admin: block
With it set, over-cap developers are blocked, "but so is everyone else if the store is unreachable". The spend-limits page puts the trade-off in one sentence: "Fail-open keeps a store outage from becoming an inference outage; fail-closed guarantees no unmetered spend."
Neither default is wrong. A team of people at keyboards usually prefers staying up, because a person notices a problem. A fleet of unattended agents is the case where an hour of unmetered spend is the failure. The fail closed or fail open entry walks through that choice for AI gateways in general, with LiteLLM's switch of the same kind.
What a per-developer cap leaves open
Three limits come straight from Anthropic's own pages.
The cap binds a developer, not an agent. The scope list has user, rbac_group and organization. There is no agent scope. The overview adds: "A gateway sign-in token identifies the developer who approved the sign-in, not the program that uses it." If one developer runs several agents under one sign-in, they draw on one cap, and the record cannot tell them apart by identity.
Unattended pipelines are outside it. The overview states: "There is no service-token flow for unattended pipelines. Gateway sign-in always runs the browser device flow, so a CI job with no developer to approve the sign-in can't authenticate; configure those against your provider directly." A fleet of headless agents is the case this describes, and the gateway's caps do not reach it.
The gateway is not the only route. The deployment guide says: "the gateway doesn't enforce that the only route to a model goes through it. A developer with their own credential can still call the provider directly, so closing that path is a network policy decision". The same idea runs through the per-agent key and budget comparison: a limit that sits beside a credential only holds if the credential cannot be used elsewhere.
One more point on records. The spend-limits page documents an admin mutation trail: "who changed which cap, with before/after snapshots", kept 365 days by default (admin.audit_retention_days). That answers who raised a cap. The pages read do not describe a signed or tamper-evident record of each refused call, so a reader who needs that has to ask where it would come from.
Where Mandare fits, and where it does not
Mandare solves a neighbouring problem with a different shape: the limit belongs to an agent, is signed by a human once, and is enforced by a door in the request path. As of @mandarelabs/cli 0.1.0, checked against the public repository at commit 327442e:
- A mandate is signed by the owner and carries caps per transaction, per day, per task and in total, set with
mandare mandate issue --agent <did:key> --per-day 20. The concepts page describes the model. - Each agent holds its own key and signs its requests, so the cap attaches to an agent identity rather than to a login.
- Caps are enforced by reservation: the estimated cost is reserved inside the same ledger transaction as the intent entry, before the call. A refusal is a ledger entry too.
- Model IDs "match exactly, so an unlisted variant is refused, never priced as a sibling". That is the opposite choice to a flat unknown-model tier: refuse instead of bill.
- Spend enforcement is fail-closed on every door.
The runaway-loop demo, run with pnpm demo, shows the refusal. The transcript below is copied from docs/demos/S2-runaway-demo.txt in the repository, with cuts marked:
…
code: PER_DAY_EXCEEDED
reason: per-day budget exceeded: reserved 0.00 EUR + settled 19.723587 EUR + estimate 0.278853 EUR > cap 20.00 EUR
the refusal itself is ledger entry 59034994bfacad09…
…
DEMO PASS: 71 calls, €19.723587 settled, call #72 refused,
refusal on the ledger, chain VALID, counters == replay(ledger).The demo uses a mock provider and needs no API keys: the enforcement is real, the money is not. The runaway loop entry explains the run.
The limits sit next to those claims. The door proxies Anthropic POST /v1/messages and OpenAI or OpenRouter POST /v1/chat/completions, and nothing else. The repository documents an MCP server for Claude Code and a skill, but has no example or test that routes Claude Code's model traffic through the door, so this entry makes no claim that it works. The Mandare docs read for this entry describe no SSO sign-in and no identity-provider group scopes, and there is no hosted service. Spend is bounded by reservation only given a correct price table. There has been no external audit of the code. On those points the Claude apps gateway is the better choice for a team of developers on a cloud commitment, and the two are not alternatives: a gateway for people can sit next to a per-agent mandate for the agents.
Questions
How to set a spend limit per developer for Claude Code?
Run a Claude apps gateway with an admin: block, then POST a cap to /v1/organizations/spend_limits with a scope (user, rbac_group or organization), an amount in USD cents and a period (daily, weekly, monthly). The gateway enforces it on each /v1/messages request and returns 429 once a developer is over.
What happens when a developer hits the cap?
The gateway answers 429 with error.type: billing_error and the header x-should-retry: false. For a cap above zero the message names the UTC date the cap resets. An admin can raise the cap, or it resets on the next UTC day, week or month.
Does the Claude apps gateway fail open or closed?
Open by default. If Postgres is unreachable or the two-second query times out, the request proceeds and the gateway logs a warning. Setting enforcement.fail_closed_on_error: true blocks instead, and blocks everyone else too while the store is down.
Can a spend cap stop a developer from going around the gateway?
No. Anthropic's deployment guide says the gateway "doesn't enforce that the only route to a model goes through it". A developer with their own provider credential can call the provider directly unless network policy blocks that path.
Sources
- Claude apps gateway spend limits · Anthropic (Claude Code documentation)
- Claude apps gateway configuration reference · Anthropic (Claude Code documentation)
- Claude apps gateway overview and quickstart · Anthropic (Claude Code documentation)
- Claude apps gateway deployment and operations · Anthropic (Claude Code documentation)
Run it yourself: 3 commands, no API keys.
github.com/mandarelabs/mandare →