Skip to main content
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.
It is not the same as a quota refusal. Organization quotas answer 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

  1. Lower max_output_tokens. A decision answer needs few output tokens; the examples in these docs use 16.
  2. Shrink the input. Trim the state to the fields the questions need, and shorten instructions and question text.
  3. Check the ceiling with GET /v1/quota (needs usage_read). If request_spend_ceiling_micros is below 20,000, your organization’s configuration lowered it.
  4. Retry with a new Idempotency-Key. max_output_tokens is not part of the key’s identity, so the old key would replay the pending run instead of running the smaller request.

Example

Reading the ceiling before you size a run: