Budgets

Spending controls are enforced by the gateway before any work is done. A request that would break a limit is rejected; it is not executed, not charged and produces no receipt.

Control layers

insufficient_balance and budget_exceeded both use HTTP 402.

Order of checks

For an inference request:

1. API key authentication and the inference scope.
2. Model resolution, then the project and key model allowlists.
3. Tool support, if tools were sent.
4. The key's rate limit, then the project's rate limit.
5. In one transaction holding the project's balance lock: the key's monthly limit, the project's monthly budget, then the balance reservation.

Sandbox executions follow the same sequence with the sandboxes scope and no model checks. Holding the balance lock serializes concurrent requests in a project, so parallel requests cannot collectively exceed a budget.

Committed spend

Monthly limits are compared against committed spend, not only settled charges:

committed = settled cost of completed inference requests and sandbox executions this UTC month
          + reservations of inference requests and sandbox executions still in flight

reject if committed + this_request_reservation > limit

Because the new request is counted at its reservation (its maximum possible cost), a request can be rejected even though its actual cost would have fitted. Lower max_completion_tokens or timeout_seconds to shrink the reservation. Months reset at 00:00 UTC on the first day of the month.

Balance

The balance is the hard floor. A reservation larger than the available balance fails with insufficient_balance, and database constraints guarantee the balance never goes negative. Add credit with a USDG purchase on Robinhood Chain.

Project monthly budget

An optional cap on the project's committed spend per month, set in the project policy in the console. When unset, only the balance limits spending. The error message states the budget, for example "This request would exceed the project's monthly budget of $50.00."

Key monthly limit

An optional cap on committed spend through a single API key. It is checked before the project budget. Use it to bound the exposure of any one service or integration. See API Keys.

Agent run budget

Each hosted agent has a run budget: a hard ceiling on the total cost of a single run, which cannot exceed the project's maximum agent run budget. The gateway enforces it per operation:

• Before each model call, output tokens are capped at what the remaining budget can pay for after the estimated input cost. If fewer than 64 output tokens are affordable, the call is refused.
• A sandbox execution is refused if its reservation (the full timeout) exceeds the remaining budget.
• A refused operation ends the run with status budget_exceeded.

Project balance, project budget and project rate limits still apply to agent runs. See Agents.

Project policy defaults

Handling budget errors

{
  "error": {
    "type": "budget_exceeded",
    "message": "This request would exceed the project's monthly budget of $50.00.",
    "request_id": "req_01K58ZW7B2D9F4H6K8M1P3R5T7"
  }
}

• Do not retry immediately. A 402 will keep failing until the balance, budget or request changes.
• Distinguish insufficient_balance (add credit) from budget_exceeded (raise the limit, wait for the month to reset, or reduce the request's maximum).
• Alert on these errors: they indicate spend reaching a limit you set deliberately.