Errors & limits

Standard OpenAI error envelope, so existing error handling works as-is.

HTTP	Code	What it means
401	invalid_api_key	The key is missing or wrong.
401	key_revoked	The key was revoked in the console.
402	insufficient_credits	Your prepaid balance is spent. Add credits and the same key resumes working.
404	model_not_found	That model id is not enabled. GET /v1/models for the live list.
429	rate_limit_exceeded	You set a requests-per-minute limit and a client went over it. Retry after a short pause.
429	quota_exceeded	This key hit its daily spend cap. Raise the cap, use another key, or wait for the UTC day to roll over.
5xx	upstream error	The provider is failing. We retry across providers before surfacing this.

{
  "error": {
    "message": "Model 'claude-haiku-3' is not configured on this gateway.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

json

What bounds your spend

Your prepaid balance, always. When it is gone every key returns 402 and nothing further is billed.
A daily cap on each key, if you set one. Give a key a dollar figure when you create it, or edit it later on the API keys page. Once that key's billed spend for the UTC day reaches the figure, it returns 429 quota_exceeded until the day rolls over.
The cap is per key, not per account: a capped key stopping does not stop your other keys. This is what makes a cap usable on a CI runner or a shared demo key.

How the cap is counted

It counts the same dollars your Activity ledger and your invoice do. No separate meter.
The keys page shows the running total beside the cap, so you can see the exact figure being compared.
The tally refreshes about once a minute and counts charges that are still settling, so a burst can carry a little past the number before it bites.

Rate limit

Optional. Set a requests-per-minute limit and anything above it gets 429 rate_limit_exceeded.
It applies to your account, not to one key: every key meters against one wallet and shares the window.
Treat it as a runaway valve, not a hard ceiling. The window is counted per gateway instance, so a burst fired in parallel can briefly exceed it while a single looping client is held exactly.

New limits take effect within about 15 seconds.

Failures

Requests that fail are never billed.
They still appear in Activity at zero cost with the upstream reason, so a spike of errors is visible without costing anything.