Reference
Full error code reference Gateway error types with HTTP status, meaning, and what to do next.
ToRouter includes a type code in error responses (usually the JSON type field). The tables below cover codes the gateway emits itself. Errors that originate upstream (OpenAI / Anthropic / Gemini) keep the provider's original type and message — see their docs for those.
Type Status Meaning Fix API_KEY_REQUIRED401 No API key in request headers Send Authorization: Bearer sk-*** INVALID_API_KEY401 Key not recognised Check for typos; the key may have been revoked API_KEY_DISABLED401 Key was disabled in /keys Re-enable or create a new key API_KEY_EXPIRED403 Key is past its configured expiry Extend expiry or rotate API_KEY_QUOTA_EXHAUSTED429 Key hit its configured spending cap Raise the cap or rotate USER_NOT_FOUND401 Key's owning user is missing Contact support USER_INACTIVE401 Owning user is suspended / unverified Verify email; check account status
Type Status Meaning Fix ACCESS_DENIED403 Client IP not in the key's allowlist (or in its blocklist), or model not in the key's whitelist Update the key's IP / model restrictions SUBSCRIPTION_NOT_FOUND403 This key needs an active subscription but none is on file Complete subscription in /subscriptions INSUFFICIENT_BALANCE403 Account balance ≤ 0 for pay-per-token Top up in /billing/topup
Type Status Meaning Fix rate limit exceeded (top-level error)429 Per-IP / per-key request rate limit Back off; raise limit USAGE_LIMIT_EXCEEDED429 Subscription daily / weekly / monthly window cap Wait for window roll-over or move to a higher-usage plan tier SUBSCRIPTION_INVALID403 Subscription is paused, cancelled, or otherwise invalid Renew in /subscriptions
Type Status Meaning Fix api_key_in_query_deprecated400 API key passed in ?key= or ?api_key= (no longer supported) Move the key to the Authorization header invalid_request_error (passthrough from upstream)400 Body fails upstream validation Fix request shape
Type Status Meaning Fix upstream_unavailable502 / 503 Every candidate channel failed Retry with backoff; check the usage dashboard or usage details upstream_timeout504 Upstream didn't respond in time Retry; try a smaller model or shorter prompt INTERNAL_ERROR500 Unexpected gateway error Retry; report with x-request-id if persistent
Response shape differs slightly by protocol (OpenAI, Anthropic, Gemini), but the same type always means the same thing.
{ "error" : { "type" : "API_KEY_EXPIRED" , "code" : "API_KEY_EXPIRED" , "message" : "API key 已过期" } }
type / code: match against the tables above.message: human-readable detail; may be in Chinese for legacy codes.Response header x-request-id: include when reporting an issue.
ToRouter Docs