Errors and troubleshooting
Diagnose using HTTP status, machine code, request source and request ID.
On this page
Request and account
401 · Invalid keyThe request lacks valid credentials. Gateway codes include unauthorized, invalid_api_key and key_disabled. Do not diagnose from a translated client message alone.402 · Insufficient balanceGateway insufficient_balance means insufficient spendable account funds, including exposure reserved by video jobs. Other services may use different codes; establish the request source.403 · Model not allowedmodel_not_allowed means the model can be routed but this key lacks permission. It is separate from account balance.403 · Key quota exhaustedquota_exhausted means this key reached its quota, not an empty account balance or missing model permission.404 · Model not foundmodel_not_found covers misspellings, a different key group, disabled or retired models and stale alias targets.405 · Method not allowedThe URL exists but the HTTP method is unsupported. Model listings use GET; generation requests use POST.Diagnosing Author anthropic is bannedThis wording may come from a client, another proxy or an upstream. Neither the wording nor an error JSON shape alone establishes its source.
Channels and upstreams
Also distinguish 503 group_disabled, channel_disabled, channel_unconfigured and channel_budget_exhausted. These describe groups/channels, not model retirement. Gateway-authored messages follow Accept-Language; machine codes and HTTP statuses remain unchanged.
429 · Rate limitedrate_limit_exceeded normally identifies the gateway's per-key limit; upstream_rate_limited identifies an upstream limit. Neither proves model retirement.502 · Upstream model missingupstream_model_missing means a catalog route was found but the upstream could not find the model. Other 502 codes may indicate upstream authentication, connection or generic failure.504 · Upstream timeoutupstream_timeout means the gateway exceeded its upstream wait deadline. Video jobs are asynchronous; a local client timeout may leave the submission result unknown.
Models, parameters and output
400 · Troubleshooting tool callsupstream_bad_request means the upstream rejected the request. Unsupported tools are one possible cause; parameters, tool schema, content format or excessive context may also trigger it.400 · Model endpoint mismatchmodel_endpoint_mismatch means the endpoint does not match the model category, such as using an image model on a chat endpoint.200 · Success without textNull content is not always an error: a tool reply may contain only tool_calls. finish_reason length indicates an output limit, which reasoning may consume on some models. Not all empty replies have this cause.