multi-router.aidocs

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:

BudgetMessageRetry-After
Daily, weekly or monthlybudget bdg_4Rk8Vb2NwQ is exhausted for this period; it resets at 2026-11-01T00:00:00ZSeconds until the reset.
Lifetimebudget bdg_4Rk8Vb2NwQ is exhausted3600

Response by endpoint

Each endpoint returns the block in its own error format:

EndpointBody
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:

ActionWhen
Wait the seconds in Retry-AfterFor a daily budget near its reset.
Show the message to the userFor interactive tools such as Claude Code, which display it.
Ask for more budgetFor people on a tools policy, with Request more budget in the Portal.

Token counting requests stay outside budgets.

Status and UsageBudgets API
Was this helpful?