What Claude apps gateway spend limits do
Claude apps gateway spend limits cap how much each developer can spend through your gateway in a day, a week or a month. When a developer passes a cap, the gateway answers their next requests with a 429 until an admin raises the cap or, for any cap above $0, until the period resets. You can set a cap for one developer, for an identity provider group, or as an organization-wide default.
The reason this exists is the shape of the gateway. By default it forwards every request through one shared upstream credential on Amazon Bedrock, Google Cloud, Microsoft Foundry or Claude Platform on AWS, so the provider bill attributes everything to that one credential. On Bedrock you can turn on per-developer AWS cost attribution, but without per-developer limits a single runaway agent fleet can spend the organization's entire commitment. Spend limits give you the per-person view and the breaker.
I treat it as three layers, the CCC Spend Ladder: an organization default that catches everyone, tighter group caps for the people most likely to run long jobs, and per-user overrides for the handful of exceptions. Everything below is how to build those three rungs and what to decide before you turn it on.
Step 1: Turn on the admin API
Spend limits need the admin: block in gateway.yaml. With it configured, the gateway serves an admin API at /v1/organizations/spend_limits and enforces caps live on every inference request. The caps themselves are not written in gateway.yaml. You set them through the API, which means they live in the gateway's Postgres store and can be managed by Terraform, CI or a script.
There are two ways to authenticate to that API:
- An x-api-key header that matches a key in admin.write_keys for full access, or admin.read_keys for read-only GET access. Each key carries an id that shows up in the audit log as admin-key:<id>, so give Terraform, CI and each automation its own key.
- A gateway bearer token whose groups claim includes one of admin.admin_groups. That is full access and audits as oidc:<sub>, so use it for human admins.
Step 2: Set the organization default
Each POST /v1/organizations/spend_limits request creates or replaces one cap from three fields: scope, amount and period. Start with the organization scope, because it is the floor that catches every developer you did not think about. To set a $500 a month default for every developer, POST to that endpoint on your gateway, for example https://claude-gateway.internal.example.com/v1/organizations/spend_limits.
Send it with an x-api-key header holding your admin write key and this JSON body: {"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}. The amount is 50000 cents, which is $500.
The three fields of a spend limit
| Field | Values | What to know |
|---|---|---|
| scope.type | user, rbac_group, organization | user takes the developer's OIDC sub in scope.user_id. rbac_group takes an IdP group name in scope.rbac_group_id. organization is the org-wide default |
| amount | Whole-number string of USD cents, or null | "50000" is $500. null is unlimited. "0" blocks every request |
| period | daily, weekly, monthly | A scope can hold one cap per period. A developer over any of them is blocked |
Amounts are cents, as strings. The most common mistake I would expect here is someone typing "500" and capping the whole organization at $5. Read the cap back with GET /v1/organizations/spend_limits after every change.
Step 3: Add group caps and per-user overrides
Group caps are where most of the control lives. To layer a $100 a day cap on each member of a contractors group, send a second request.
Same endpoint, same header, with this body: {"scope": {"type": "rbac_group", "rbac_group_id": "contractors"}, "amount": "10000", "period": "daily"}. The group is named the way your identity provider names it.
For each period, the gateway resolves a developer's effective cap in this order: a per-user override first, then the most restrictive of their group caps, then the organization default, then unlimited. If someone is in two groups, the tighter group cap wins. Setting admin.group_limit_mode to max flips that tie-break to the least restrictive cap instead.
My recommendation: keep the default tie-break. Most restrictive is the safe failure, and when a senior engineer genuinely needs more room, a per-user override says so explicitly and shows up in the audit trail. The alternative, max mode with a generous engineering group, is fine when your groups map cleanly to roles, but it means one stray group membership can quietly lift a contractor's cap.
Daily and monthly caps work well together. A monthly cap sets the budget. A daily cap stops one runaway session from burning the whole month by Tuesday. Each period enforces independently, so a developer is blocked the moment they cross either.
How the gateway prices each request
After each response, a usage meter reads the token counts and adds the cost to the daily, weekly and monthly counters. It never touches the bytes going back to the client, so a metering failure cannot break a response. The meter picks the rate for each request in this order:
- A matching pricing.overrides row for the upstream that served the request (gateway v2.1.227 or later).
- List price for the upstream model ID, when the Claude Code cost table recognizes it. Anthropic, Bedrock, Google Cloud and Foundry ID forms are accepted.
- List price for the models[].id you mapped to that upstream, for upstream strings with no model name in them, such as a Bedrock application inference profile ARN or a Foundry deployment name (v2.1.218 or later).
- An unknown-model tier of $5 per million input tokens and $25 per million output tokens, so an ID the meter cannot place is never free. The gateway warns at boot and once per ID at runtime when it falls back to this tier.
Whatever rate applies is then multiplied by pricing.multiplier, which defaults to 1. If your organization has negotiated pricing, this is where the gateway's estimates get closer to your real bill. Watch the boot log for the unknown-model warning: it means your caps are being counted at a rate you did not choose.
Two details stop people gaming the meter. Client aborts are billed too: when a stream ends without the final usage frame, the meter bills a floor estimate of about four characters per output token for the text already sent. And token counting requests to /v1/messages/count_tokens are never blocked, because token counting is free.
What developers see when they hit a cap
A developer over any cap gets a 429 with error.type billing_error and the header x-should-retry: false, which tells the client not to retry. For a cap above "0", the message gives the UTC date the cap resets, and the response carries a retry-after header with the seconds until that period ends. If you set admin.blocked_message, the gateway appends it:
Set that message. Without it, a blocked developer has no idea who to ask, and the request lands in a general help channel. Caps reset on UTC calendar boundaries: daily at 00:00 UTC, weekly on Monday and monthly on the first. If your team is in a timezone far from UTC, tell them, because a daily cap can reset in the middle of their afternoon.
Before the block, Claude Code warns developers as they approach their cap, once past 75% and again past 95% of their most-used cap. What else they see depends on the Claude Code version on their machine and on the gateway server:
What developers see, by version
| What the developer sees | Developer's machine | Gateway server |
|---|---|---|
| Warnings at 75% and 95% | v2.1.225 or later | v2.1.225 or later |
| A Spend limit bar in /usage with the percentage used and the reset time | v2.1.251 or later | v2.1.225 or later |
| Estimated spend and the cap in dollars in that bar | v2.1.284 or later | v2.1.284 or later |
| Estimated spend today, this week and this month when no cap applies to them | v2.1.319 or later | v2.1.319 or later |
The cap also reaches the developer's status line script as a rate_limits.spend_limit object, so a team that already uses a custom status line can show remaining budget at all times. Custom status lines shows how to build one.
Decide: fail open or fail closed
Before each request, the gateway checks the developer's caps and period-to-date spend in Postgres with a two-second timeout. If the store is unreachable or times out, enforcement fails open by default: the request goes through, the gateway logs a warning, and the response carries no usage headers. Set enforcement.fail_closed_on_error to true and the gateway instead returns the same 429 billing_error with the message spend limit unavailable.
The tradeoff
| Setting | During a Postgres outage | Pick it when |
|---|---|---|
| Fail open (default) | Developers keep working. Spend in that window is not checked against caps | Developer downtime costs you more than a short unmetered window |
| Fail closed | Every request is blocked until the store is back | You run long unattended agents, or a hard spending guarantee matters more than uptime |
My call for most organizations: fail closed if you run agents unattended through the gateway, fail open if it is mostly people in interactive sessions. An unattended fleet is exactly the thing that can burn money during an outage nobody is watching. Either way, monitor the store, because fail-open only helps while your load balancer still routes traffic to the gateway.
Watch spend and keep an audit trail
- GET /v1/organizations/spend_limits/effective returns each developer's resolved cap and period-to-date spend. Add sort=spend_desc with exactly one period[] to list top spenders first.
- GET /v1/organizations/spend_limits/audit returns every cap change with before and after snapshots, newest first. Every mutation is written in the same transaction as the change.
- Names and emails in the effective view stay null until a developer's first request through the gateway, because the gateway has no user directory. Without a user_ids[] filter, it only lists people with recorded spend.
One privacy note for your security team. The q= search and user_ids[] filters ride GET query strings, so a proxy or load balancer in front of the gateway will capture them in its access logs. If your logging policy is strict about personal data, scrub those parameters there.
When a developer leaves, delete any per-user cap with DELETE /v1/organizations/spend_limits/{id}. Their spend rows keep only the pseudonymous OIDC sub and age out on the retention windows, by default 13 months for spend and 365 days for the audit trail. The principal_emails table is the only one holding name, email and groups. It ages out 90 days after last activity by default, and for an immediate erasure you delete their row from it directly.
Plan this alongside the rest of the rollout. The rollout plan covers sequencing, and managed settings covers the policy that ships to every machine next to these caps.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
How do I set a spend limit on the Claude apps gateway?
Configure the admin: block in gateway.yaml, then POST a scope, amount and period to /v1/organizations/spend_limits with an admin write key. The gateway enforces the cap live on every request.
Is a group spend limit a shared budget?
No. A group or organization cap is a per-seat default that each member inherits. Ten people under a $100 daily group cap can spend up to $1,000 a day between them.
What happens when a developer hits their Claude apps gateway spend limit?
The gateway returns a 429 with billing_error and x-should-retry: false. For caps above $0 the message gives the UTC reset date, plus your admin.blocked_message if you set one.
When do Claude apps gateway spend limits reset?
On UTC calendar boundaries: daily caps at 00:00 UTC, weekly caps on Monday and monthly caps on the first. A "0" cap never resets until an admin changes it.
Does the gateway's spend figure match my cloud bill?
Not exactly. It is the gateway's own estimate from list prices, pricing.overrides and pricing.multiplier. Use it as a circuit breaker and reconcile billing against your provider's usage reporting.
What happens to spend limits if the gateway database goes down?
By default enforcement fails open and requests go through unchecked. Set enforcement.fail_closed_on_error to true to block requests with spend limit unavailable instead.
Last reviewed by David Iya on November 15, 2026


