Error codes
What 401 / 403 / 404 / 429 / 5xx mean, a five-step triage, and practices that prevent errors.
When a call fails, start from the HTTP status code and the error message in the response body, then match it against the table below. Most issues are resolved by the first three items.
Status codes
| Status | Meaning | Common causes and fixes |
|---|---|---|
| 400 Bad Request | Invalid request | Malformed JSON or a missing required field (model, messages); check the body against the API docs |
| 401 Unauthorized | Auth failed | Key is wrong / deleted / expired; see the checklist in Authentication |
| 403 Forbidden | No access | This key or account may not call the requested model; confirm the model is available to you in the marketplace |
| 404 Not Found | Resource missing | Usually a misspelled model ID; copy the exact ID from the model marketplace |
| 429 Too Many Requests | Rate limited | Requests are too frequent. Back off (exponential intervals) or lower concurrency; contact the platform if it persists |
| 5xx | Server-side error | A temporary failure of the platform or the upstream model. Retry once with identical parameters; if it keeps failing, contact Support with the request records from the logs page |
Troubleshooting steps
- Verify the key: confirm on the "API Keys" page that the key exists and has not expired; delete and recreate if unsure.
- Verify the model ID: copy it from the model marketplace instead of typing it by hand.
- Read the error body: error responses usually carry
error.messageexplaining the exact cause (insufficient balance, missing parameter, ...). - Check the logs: the console logs page shows per-request status, latency, and consumption — check whether the failure is limited to one model or key.
- Still stuck: contact Support with the timestamps and status codes from the logs page.
Practices that prevent errors
- Use an official SDK (it handles retries, timeouts, and protocol details for you);
- Implement exponential backoff for 429 / 5xx instead of hammering retries;
- Set a spending limit on production keys so abnormal traffic cannot drain the balance.