Budget-cap recovery

When a token budget runs out, requests return 429 budget_exceeded. There is no automatic refill mid-period — monthly caps reset on the 1st (UTC), the daily cap at midnight (UTC). The message always names which budget was hit (see Account → Budgets).

curl

curl -i "$ACS_API_BASE/completions" \
  -H "Authorization: Bearer $ACS_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "llama-8b", "prompt": "Hi", "max_tokens": 8}'
# HTTP/1.1 429 Too Many Requests
# The message names the dimension that ran out — "key monthly", "account monthly"
# (aggregate across your keys), "daily", "monthly input" or "monthly output" —
# and the headroom the request needed, counting runs still in flight:
# {"error": {"code": "budget_exceeded", "type": "invalid_request_error",
#            "message": "Not enough key monthly token budget for this request (1,200 remaining, up to 4,096 needed, including active runs). Reduce the prompt, maximum tokens or number of branches, or wait for active runs."},
#  "request_id": "req_..."}

The budget is checked as a reservation before the request runs: needed is the worst case (prompt + max_tokens × n × prompts), so a request can be refused while the API keys page still shows some headroom — lower max_tokens or wait for active runs to finish. The API refuses only when there is no room for even one generated token per completion after the prompt; otherwise it clamps max_tokens to the headroom and tells you via the X-Acs-Max-Tokens-Clamped header (see Account → Budgets).

Python

from openai import APIStatusError

try:
    resp = client.completions.create(model="llama-8b", prompt="Hi", max_tokens=8)
except APIStatusError as e:
    # The SDK unwraps the {"error": {...}} envelope: e.code and e.body are the
    # inner error object (e.body["message"] names the dimension that ran out).
    # e.message is the SDK's own summary ("Error code: 429 - {...}"), not that.
    if e.status_code == 429 and e.code == "budget_exceeded":
        # Don't retry — monthly caps are sticky until the 1st (UTC), the daily
        # cap until tomorrow. Email infra@acsresearch.org to raise the budget.
        reason = e.body.get("message") if isinstance(e.body, dict) else e.message
        raise SystemExit(f"Budget exhausted ({reason}) — emailing the team for a raise.")
    raise

Gotcha

429 budget_exceeded is non-retryable; exponential backoff will not resolve it. Inspect error.code to skip retries for these cases. Requests that hit the concurrency limit are queued instead.