Find the failure by status code
| Code | Meaning | What to do |
|---|---|---|
| 400 | Malformed request or protocol mismatch | Validate JSON, route, model ID, and protocol headers (keep anthropic-version for Claude) |
| 401 | Invalid or missing key | Re-copy the key, check Bearer / x-api-key; rotate immediately if it may have leaked |
| 403 | Insufficient balance or access | Check wallet balance, key quota, model permissions, and group access |
| 429 | Rate limited | Retry with exponential backoff plus jitter, lower concurrency, and check whether the limit came from the gateway or upstream |
| 5xx | Upstream or routing failure | Keep the request id and ask an administrator to check channel health and upstream status |
| Timeout | Slow first token or interrupted stream | Use a smaller prompt, confirm stream=true, and check whether a proxy buffers SSE |
Recommended order
- Run a minimal request:
curl /v1/modelsto verify authentication. - Send one minimal chat request to separate auth errors from model/protocol errors.
- Read the error body and the request id.
- Check the usage log to see whether the request was recorded.
If an API key is exposed
- Disable or delete the key in the console immediately.
- Create a replacement and update every consumer (env vars, password managers, client config).
- Review usage logs for requests you do not recognize.
What to provide when reporting a problem
Request time, route, model ID, HTTP status, request id, client version, and a redacted error message. Never send the key itself.