Error shape
{
"error": {
"message": "monthly spend cap reached ($50.00 of $50.00).",
"type": "insufficient_quota",
"code": "spend_cap_exceeded"
}
}
Every error is {"{"} "error": {"{"} "message", "type", ... {"}"} {"}"} —
the same envelope shape as the OpenAI API, with an optional code
for programmatic handling.
Status codes
| Status | type / code | Meaning |
|---|---|---|
| 400 | invalid_request_error | missing messages, or an unknown model id not in the catalog and not "auto" |
| 401 | invalid_request_error / invalid_api_key | missing, malformed, revoked, or expired API key |
| 402 | insufficient_quota / spend_cap_exceeded | this key's monthly_spend_cap_usd is reached |
| 402 | insufficient_quota / insufficient_credits | your org's prepaid credit balance is ≤ $0 — top up at /settings/credits |
| 403 | insufficient_scope / missing_scope | this key's scopes don't include the endpoint you called |
| 403 | invalid_request_error / model_not_allowed | the requested model isn't in this key's model_allowlist |
| 429 | rate_limit_error / {"{"}rpm|tpm{"}"}_limit | this key's RPM or TPM limit is exceeded — see Retry-After below |
| 500 / 502 / 503 / 504 | upstream_error | every candidate in the fallback chain failed — see Model fallbacks; never billed (Zero-completion insurance) |
| 503 | backstop_cap_exceeded | only applies to a model we have no direct provider key for, once an operator-configured monthly backstop budget is exhausted — rare, and doesn't affect models with a direct deployment |
RPM / TPM limits
RPM and TPM are enforced per key as token buckets — a smooth rate, not a hard per-minute cliff. A denied
request gets 429 with a
Retry-After header telling you exactly
how many seconds until the next request would succeed — back off for that long rather than polling. See
Authentication to view or change a
key's limits.
Spend caps
A key's monthly_spend_cap_usd and your
org's prepaid credit balance are checked independently — hitting either one returns
402, with the
code field telling you which. As a key
approaches its cap, max_tokens is
automatically clamped to the remaining budget rather than letting one large request blow past it — see
Pricing & billing.