Budgets & Spend Control
When a Budget BlocksEnterprise
What callers receive when a budget refuses a request, on each endpoint.
A budget block refuses requests with status 429 before they reach a provider. The response names the budget by id and says when it resets, and the Retry-After header gives the seconds until then, so clients can wait or switch work. Requests already running when the block starts finish normally.
The message
A budget with a period, and a lifetime budget, return these messages:
| Budget | Message | Retry-After |
|---|---|---|
| Daily, weekly or monthly | budget bdg_4Rk8Vb2NwQ is exhausted for this period; it resets at 2026-11-01T00:00:00Z | Seconds until the reset. |
| Lifetime | budget bdg_4Rk8Vb2NwQ is exhausted | 3600 |
Response by endpoint
Each endpoint returns the block in its own error format:
| Endpoint | Body |
|---|---|
| Chat Completions, and Responses through a Codex Proxy | {"error":{"message":"…","type":"budget_exhausted","code":"budget_exhausted"}} |
| Messages and the Claude Proxy | {"type":"error","error":{"type":"budget_exhausted","message":"…"}} |
| The Gemini Proxy endpoints | {"error":{"code":429,"message":"…","status":"RESOURCE_EXHAUSTED"}} |
| The Claude Proxy Bedrock endpoints | {"message":"…","code":"budget_exhausted"} |
| The Claude Proxy Vertex endpoints | {"error":{"code":429,"message":"…","status":"RESOURCE_EXHAUSTED","details":[{"@type":"type.googleapis.com/google.rpc.ErrorInfo","reason":"budget_exhausted","domain":"multi-router.ai"}]}} |
On the Bedrock and Vertex endpoints the response also carries the header x-mr-error-code: budget_exhausted, which tells a budget block apart from a rate limit.
Fallback and weighted routers
Budgets that cover a fallback or weighted router are checked for each member: when they block a member's model, the router tries the next member, so a block on one model moves traffic to the others. A block on the fallback or weighted router as a whole refuses the request.
Handling a block
A client that receives a budget block can:
| Action | When |
|---|---|
Wait the seconds in Retry-After | For a daily budget near its reset. |
| Show the message to the user | For interactive tools such as Claude Code, which display it. |
| Ask for more budget | For people on a tools policy, with Request more budget in the Portal. |
Token counting requests stay outside budgets.