Error codes

type mapping: 401 → authentication_error, 403 → permission_error, 429 → rate_limit_error, ≥ 500 → api_error, else invalid_request_error.

Code	HTTP	When
missing_api_key	401	No / empty bearer token
invalid_api_key	401	Unknown key hash
key_revoked	401	Revoked
key_expired	401	Expired
key_inactive	401	Non-active status
key_blocked	403	Blocked key
model_access_denied	403	Model not in the key allowlist
scope_blocked	403	User, team, org or app is blocked
customer_blocked	403	Customer is blocked
guardrail_blocked	403	Pre or post guardrail block
budget_exceeded	429	Key, scope, tag or customer budget exhausted
rate_limit_exceeded	429	RPM or TPM window exhausted
invalid_request	400	Bad JSON or missing model
model_not_found	404	No enabled deployments (and fallbacks exhausted)
upstream_unavailable	502	Every deployment attempt failed
internal_error	500	Key context / DB failure
unhealthy	503	Health / readiness probe failure

Rate-limit messages include the scope: RPM limit exceeded for key (limit N/min), TPM limit exceeded for team (limit N tokens/min). Scopes: key, team, application, customer (chat only).

Budget messages include the entity and spend vs max, for example Budget has been exceeded! Key=<alias> Current cost: X, Max budget: Y.