HTTP errors
Chat and image errors usually use an error object. Video errors can use code and message. A parameter error or model_not_found takes priority over the general 5xx retry rule.
| HTTP status | Error code or message | Meaning | Retry or not | What to do |
|---|---|---|---|---|
| 400 | invalid_request or missing_model | A required field is missing or outside its limit. | Do not retry. | Fix the named field. For example, kimi-k2.7-code-official accepts only temperature 1 and top_p 0.95. For Kling v3 image models only (kling/kling-v3-image-generation and kling/kling-v3-omni-image-generation), n must be 1 to 9. For wan3.0-video and wan3.0-video-prime only, duration is 2 to 30 whole seconds or -1. Wan duration=-1 lets the model choose the length; TokenRoc reserves 30 seconds and settles to the length actually generated. See the image and video guides for each model's other limits. |
| 401 | Invalid or missing API key | Authentication failed. | Do not retry. | Send Authorization: Bearer with an active API key. Check the API Keys page and remove extra spaces. |
| 403 | insufficient_user_quota | Your balance cannot cover the request or video reservation. | Do not retry until fixed. | Add credit on the Wallet page, or reduce the request cost. |
| 403 | pre_consume_token_quota_failed or access_denied | The API key limit, model permissions, or IP rules reject the request. | Do not retry until fixed. | Check the API key spending limit, allowed models and IP rules. |
| 429 | Rate limit message | Too many requests or a temporary capacity limit. | Retry with backoff. | Reduce concurrency. Wait 2, 4, then 8 seconds between attempts. |
| 503 | model_not_found | The model ID is wrong or unavailable to your API key. | Do not retry. | Check the exact model ID in Model Square and the API key model permissions. |
| Other 5xx | Temporary server error | A temporary gateway or model service failure. | Retry with backoff, max 3 times. | Wait 2, 4, then 8 seconds. For video submission, check Task Logs before resubmitting so you do not create a second task. |
| 400 | task_not_exist | No task with this ID belongs to your account. | Do not retry. | Check the saved task ID and use an API key from the account that created it. |
| 400 or 5xx | invalid_request or convert_request_failed with a parameter error | The request cannot be converted for this model. | Do not retry unchanged. | Fix the field named in the message, even if the status is 5xx. |
| 200 | error.type: ali_error | Image generation failed despite an HTTP 200 response. | Do not retry unchanged. | Check error.code and error.message before reading data. Change the prompt or inputs if the message requires it. |
| 5xx | bad_response with aliAsyncTaskWait timeout | Image generation did not finish within the wait period. | Retry later with backoff, max 3 times. | Check Usage Logs before retrying. Contact support if it keeps failing. |
| Varies | ali_api_error or fail_to_fetch_task | Video submission or task lookup failed. | Follow the status and message. | Fix parameter or content errors. For 429 or other temporary 5xx errors, use backoff. Keep the same task ID when checking an existing task. |
What to send support
Send the request ID or task ID, model ID, HTTP status, error code and message, and the time of the request. The response header X-Oneapi-Request-Id contains the request ID. Error messages can also include it. For video, save the task ID returned by the submit request or find it in Task Logs.
Use the contact page. Never send your API key or a signed download link.