budget_exhausted means the run’s own spend budget could not cover a model call. Read this page when large runs fail with this code while small ones succeed.
What happened
Route:POST /v1/runs.
Every run has a spend ceiling of at most 20,000 micro-USD ($0.02). Your organization’s configuration can lower it, never raise it; GET /v1/quota reports it as limits.request_spend_ceiling_micros. The run holds that ceiling while it runs.
budget_exhausted is raised when the run’s own budget cannot cover what it is about to do:
- the reservation for the run was refused;
- the spend ceiling used when choosing a model was hit;
- the run’s budget of calls or tokens ran out.
429 before the run exists; see organization_spend_quota_exhausted. It is not a credit problem either; that answers 402 insufficient_credits.
The run was refused before the model served it. You are not charged, and the hold is released, but the run stays pending. A replay with the same Idempotency-Key returns 202 with "state": "pending".
How to fix
- Lower
max_output_tokens. A decision answer needs few output tokens; the examples in these docs use16. - Shrink the input. Trim the
stateto the fields the questions need, and shorteninstructionsand question text. - Check the ceiling with
GET /v1/quota(needsusage_read). Ifrequest_spend_ceiling_microsis below 20,000, your organization’s configuration lowered it. - Retry with a new
Idempotency-Key.max_output_tokensis not part of the key’s identity, so the old key would replay the pending run instead of running the smaller request.
Example
Related
- Spend limits and quotas - the per-request ceiling and the period limits.
- Models and pricing - what a run costs per token.
- Limits - every size and count limit in one table.
- Idempotency - when to reuse an
Idempotency-Keyand when to send a new one. - Problem codes - every code, its status, and whether a retry can help.