Guides
Troubleshooting
Every gateway error returns a JSON envelope and an x-gateway-error-code header. Start from the code.
Error lookup
| Error | Cause | Fix |
|---|---|---|
401 missing_api_key | No key header reached the gateway. | Send Authorization: Bearer <key> or x-api-key. Check proxies are not stripping headers. |
401 invalid_api_key | Key is wrong, revoked or deleted. | Create a new key in the dashboard and update your environment. |
402 quota_exhausted | Your balance is zero. | Add credit or redeem a gift card in the dashboard. |
403 permission_denied | Account not verified, or key not allowed for this model. | Complete Telegram verification in the dashboard, or choose a model from GET /v1/models. |
404 invalid_model | Model id is unknown or not enabled. | Call GET /v1/models and copy the id exactly. |
404 not_found | Wrong path. | The OpenAI base URL ends in /v1. The Anthropic base URL does not. |
400 invalid_json | Body is not valid JSON. | Set Content-Type: application/json and validate the payload. |
413 payload_too_large | Body exceeds the request size limit. | Trim the prompt or attached content. |
429 rate_limit_exceeded | Per-minute limit or plan spend window reached. | Honour Retry-After; see Rate limits. |
502 / 503 / 504 | Provider error, busy, or timeout. | Retry with backoff. Failover to other providers is automatic. |
Streaming problems
Streams are sent as text/event-stream without buffering. If a reverse proxy in front of your app buffers responses, disable buffering for that route. An error after the first byte arrives as an event: error frame, because the 200 status was already sent.
Checking your key and balance
GET /v1/usage with your key returns remaining tokens and status. It is the quickest way to confirm a key works and has credit.