Errors and Troubleshooting
Record the timestamp, HTTP status, model, endpoint, and request ID first. Remove the API key before sharing diagnostics.
Common status codes
| Status | Common cause | Recommended action |
|---|---|---|
400 | Invalid JSON, parameters, or request format | Check model, stream, Content-Type, and the endpoint example |
401 | Missing, invalid, disabled, or expired key | Set or create the key again and verify the auth header |
403 | Account, project, or upstream permission is missing | Use a model with the required capability or contact the administrator |
404 | Wrong path, missing model, or unsupported endpoint | Check duplicate /v1 segments and refresh the model list |
409 | Request state conflict | Avoid duplicate submission and follow the response details |
429 | Concurrency, rate, capacity, or upstream limit | Honor Retry-After, back off, or try later |
500 | Internal gateway error | Keep the request ID, retry later, and report it if persistent |
502 | Invalid upstream response or connection failure | Retry later and report persistent failures with a request ID |
503 | No compatible account is available | Switch models, retry later, or contact the administrator |
504 | Upstream timeout | Reduce request complexity or increase the client timeout |
Selected model is at capacity
No compatible upstream account for that model can accept the request immediately. This usually reflects pool load, rate-limit windows, or capacity, not a corrupted local configuration.
- Wait a few seconds and retry with exponential backoff.
- Confirm that the model still appears in
/v1/models. - Temporarily switch to an alternative model when available.
- If the issue persists, provide the timestamp, model, and request ID to the administrator.
High time to first token
Time to first token includes network setup, queueing, account selection, upstream handshake, pre-inference work, and tool preparation.
- Use streaming to improve perceived latency.
- Avoid sending unnecessarily large context on every request.
- Compare with a lower reasoning effort.
- Measure several requests and inspect P50/P95 instead of one sample.
- Separate slow connection setup from slow upstream generation.
An image was generated but the client shows nothing
Inspect the raw JSON first. If b64_json exists, generation succeeded and the issue is client rendering. If no image field exists, check the model, group, and request format. See Image Generation and Edits.