AI GridDocs
Sign Up

Caps and spend controls

The three controls that bound what a call can spend — and the errors you see when one bites.

Updated Sep 9, 2026

Spend on the Grid is bounded by three independent controls, all checked before a provider is called. A call that trips any of them is refused and costs nothing.

Control Set by Bounds Breach error
Project wallet balance whoever funds it the hard bound — no funded balance, no call 402 insufficient_budget
Invocation policy organization Owner models, output size, daily/monthly spend 403 policy_denied · 403 budget_limit
Key spending limit the key's creator one key's spend per window 403 key_limit

The wallet is the hard bound#

Money lives on the project wallet, one per project. Before a call runs, admission computes a reservation — a conservative estimate of its cost — and checks it against what the wallet can actually spare: funded balance, minus everything already charged, minus all outstanding holds. If the reservation does not fit, the call fails with 402 insufficient_budget and nothing is reserved.

Every admission holds at least one micro-USD, so even a call whose price rounds to zero requires a funded, available wallet. No cap or policy can raise this ceiling — topping up is the only fix.

Key spending limits#

When you create an API key, you can give it a spending limit: an amount in micro-USD (limitMicro) and a reset window — daily, weekly, monthly or lifetime.

  • Windows are UTC: a calendar day, a week starting Monday 00:00 UTC, a calendar month. lifetime never resets.
  • Outstanding holds count. A reservation whose outcome is not yet known keeps counting against the limit until it settles — even across a window boundary.
  • When the limit is reached, calls fail with 403 key_limit until the window rolls over or the holds clear.

The limit is fixed at creation and survives rotation unchanged. To change it, issue a new key. There are no key-owned funds — the limit only restricts how much of the project wallet one key may draw.

Invocation policy ceilings#

An organization Owner can define named invocation policies with three kinds of ceiling:

  • allowedModels — an allowlist of products; a call naming anything else is refused
  • maxOutputTokens — a cap on the requested output size (at most 8192)
  • dailyMicro / monthlyMicro — spending ceilings, in micro-USD; when both are set, the daily ceiling must sit below the monthly one

A policy applies to the whole organization, or to one project when it carries a projectId. All active applicable policies remain in force at once: allowlists intersect, and every ceiling must have room for the new reservation. Outstanding holds count against policy ceilings the same way they count against key limits.

A model or output-size refusal returns 403 policy_denied; an exhausted ceiling returns 403 budget_limit. Both are hard stops — there is no overflow into another policy, and topping up the wallet does not lift a policy ceiling. The fix is to edit the policy, which only the Owner can do.

When a limit bites#

You see Meaning Fix
402 insufficient_budget the project wallet cannot cover the reservation top up
403 budget_limit an Owner policy's daily or monthly ceiling is reached the Owner raises or relaxes the policy, or waits for the window
403 key_limit the key's own spending limit is spent for its window wait for the reset, or issue a key with a higher limit
403 policy_denied the model or requested output size is not allowed call an allowed model, or lower max_tokens

Separately from spend, admission also rate-limits callers to 30 requests per minute within an organization — see Rate limits.

Next#