API Reference
Errors, status codes, and request_id
Gateway errors distinguish invalid requests, authentication, credit, rate limits, and upstream failures.
Record HTTP status, error code, and request_id first. Fix authentication and validation errors instead of automatically retrying them.
- Auth
- 401
- Credit/access
- 402 / 403
- Rate limit
- 429
- Correlation
- request_id
Status matrix
| Status | Meaning | Action |
|---|---|---|
| 400 | Invalid JSON, field, or model parameter | Fix, then send again |
| 401 | Missing, invalid, or disabled Key | Recopy the Key and update clients |
| 402 / 403 | Insufficient balance or group access | Check account state in Dashboard |
| 404 | Path, model, or capability not found | Refresh /v1/models |
| 429 | Rate limited or temporarily unavailable | Honor Retry-After |
| 5xx | Gateway or upstream failure | Bounded retry with request_id |
Minimal diagnosis order
- 1Confirm Dashboard signs in.
- 2Review account state, balance, and API Key.
- 3Recopy Gateway, Key, and model ID.
- 4Call /v1/models to verify authentication.
- 5Send a minimal non-streaming cURL, then return to the SDK or IDE.