budget_exhausted

What it means

The request would breach a real-time spend cap. The cap, what was consumed and when it resets ride on x-ace-budget-cap-usd, x-ace-budget-consumed-usd and x-ace-budget-resets-at as well as in the body.

How to recognise it

The gateway answers HTTP 402 with x-ace-error: budget_exhausted on the response, and a body in the shared error envelope:

{
  "error": {
    "message": "...",
    "type": "budget_exhausted",
    "code": 402
  }
}

On a vendor-shaped surface (/anthropic/…, /gemini/…, /bedrock/…) the body wears that vendor's error envelope instead; the x-ace-error header is the same everywhere.

Is it ACE or the provider?

x-ace-error is present only on errors ACE originated. A vendor error relayed from upstream — a real provider 429, a provider 401 for a bad pass-through key — carries no x-ace-error, and its own type and code mean what the provider says. Read the header before deciding whether to retry, re-mint a key or surface the error.

Other 402 errors

• onboarding_incomplete: Missing provider key (stored/pass-through) or unconfigured model/router.

Related

• Error contracts & status codes: the full taxonomy
• Response header specification
• Echo mode: reproduce a call without spending