Error Handling
Updated: Nov 11, 2026
Error response formats, error codes, and recommended handling for Chat and Images APIs.
This page applies to Chat and Images APIs.
These APIs can return two types of errors, each with its own response format: API errors and native model errors.
1. API Errors
If a request fails validation or cannot be processed by the platform, the response body has the following format:
{
"requestId": "7f0d6ef8-a3c9-4f61-8e6f-1d5c8a720134",
"code": 40000,
"message": "bad request:model must be not empty"
}| Field | Type | Description |
|---|---|---|
| requestId | string | Request ID. Matches the X-Vod-Request-Id response header. |
| code | integer | Platform error code. Use it together with the HTTP status code to identify the error. |
| message | string | Error message. Details may follow the colon. |
The API can return the following error codes:
| HTTP Status | code | message | Common Causes |
|---|---|---|---|
| 400 | 40000 | bad request | Invalid JSON, missing model, or an X-Vod-Request-Id that is not 16–64 characters long |
| 401 | 40100 | unauthorized | Missing, malformed, or expired API Key, or an unavailable account |
| 403 | 40300 | forbidden | The client IP is not on the API Key's allowlist |
| 404 | 40400 | not found | The request path does not exist |
| 404 | 40402 | model not exist | The requested model does not exist |
| 404 | 40403 | model not exist in this path | The model is not available on this native API path |
| 405 | 40500 | method not allowed | The path exists, but the HTTP method is not supported |
| 409 | 40900 | conflict | The same account reused an X-Vod-Request-Id within 8 hours |
| 429 | 42900 | rate limiting | The request rate, concurrency, or token quota was exceeded |
| 500 | 50000 | internal error | An internal error occurred while processing the request |
| 502 | 50200 | bad gateway | The upstream model service is temporarily unavailable |
| 503 | 50300 | service unavailable | The API or model service is temporarily unavailable |
2. Native Model Errors
If a request passes validation and reaches the model, any error returned by the model is passed through unchanged. These errors follow the format of the protocol you call (OpenAI, Anthropic, or Gemini) rather than the requestId/code/message format above. An OpenAI-format error looks like this:
{
"error": {
"message": "The requested model is unavailable.",
"type": "invalid_request_error",
"param": "model",
"code": "model_not_found"
}
}Fields and values are defined by the model provider. The main differences between protocols are:
- OpenAI:
error.codeis usually a string. - Anthropic:
error.typeindicates the error type. - Gemini:
error.codeis usually a number.
3. Recommended Handling
- If the response body contains a top-level integer
codegreater than 0, handle it as an API error. - Otherwise, parse the error according to the protocol you called (OpenAI, Anthropic, or Gemini).
- Then act on the HTTP status code:
400,401,403,404,405,409: Correct the request, credentials, or path before trying again.429: Reduce the request rate or concurrency, then retry.500,502,503: Retry a limited number of times with backoff, using a newX-Vod-Request-Idfor each retry.
When contacting support, include the X-Vod-Task-Id from the response headers.