错误处理
更新时间：2026-11-11
API 调用错误与模型原生错误的响应结构、错误码及客户端处理建议。
本文适用于聊天（Chat）、图片（Images）接口。视频接口的错误以各接口文档及对应原厂说明为准。
这些接口可能返回两类错误：API 调用错误和模型原生错误，两类错误的响应结构不同。
1. API 调用错误
请求未通过平台校验或平台处理失败时，固定返回以下 JSON 结构：
{
"requestId": "7f0d6ef8-a3c9-4f61-8e6f-1d5c8a720134",
"code": 40000,
"message": "bad request:model must be not empty"
}| 字段 | 类型 | 说明 |
|---|---|---|
| requestId | string | API 服务请求标识，与响应头 X-Vod-Request-Id 对应 |
| code | integer | API 服务业务错误码，与 HTTP 状态码共同判断错误类型 |
| message | string | 基础错误信息，冒号后可能附带具体原因 |
下表仅列出当前 API 服务实际可能返回的错误码：
| HTTP 状态码 | code | 基础信息 | 常见原因 |
|---|---|---|---|
| 400 | 40000 | bad request | JSON 无效、缺少 model，或 X-Vod-Request-Id 长度不在 16～64 个字符范围内 |
| 401 | 40100 | unauthorized | API Key 缺失、格式错误、已失效，或账号不可用 |
| 403 | 40300 | forbidden | 客户端 IP 不在 API Key 白名单中 |
| 404 | 40400 | not found | 请求路径不存在 |
| 404 | 40402 | model not exist | 请求的模型不存在 |
| 404 | 40403 | model not exist in this path | 当前原生 API 路径不支持该模型 |
| 405 | 40500 | method not allowed | 路径存在，但 HTTP 方法不受支持 |
| 409 | 40900 | conflict | 同一账号在 8 小时内重复使用相同的 X-Vod-Request-Id |
| 429 | 42900 | rate limiting | 超过请求频率、并发数或 Token 限额 |
| 500 | 50000 | internal error | API 服务处理请求失败 |
| 502 | 50200 | bad gateway | 上游模型服务暂时不可用 |
| 503 | 50300 | service unavailable | API 服务或模型服务暂时不可用 |
2. 模型原生错误
请求通过平台校验并已发送给模型后，模型返回的错误会原样返回给调用方。这类错误遵循所调用模型协议（OpenAI、Anthropic、Gemini）的错误结构，不使用上面的 requestId/code/message 结构。以 OpenAI 协议为例：
{
"error": {
"message": "The requested model is unavailable.",
"type": "invalid_request_error",
"param": "model",
"code": "model_not_found"
}
}具体字段和值以模型厂商实际响应为准，各协议的差异如下：
- OpenAI：
error.code通常为字符串。 - Anthropic：使用
error.type表示错误类型。 - Gemini：
error.code通常为数字。
3. 客户端处理建议
- 先判断响应体顶层是否有整数类型的
code且大于 0。有则按 API 调用错误处理。 - 否则按所调用的 OpenAI、Anthropic 或 Gemini 原生协议解析错误体。
- 按 HTTP 状态码处理：
400、401、403、404、405、409：先修正客户端请求、权限或调用路径。429：降低请求速率或并发量后再发起新请求。500、502、503：可使用退避策略有限重试，并为重试请求生成新的请求头X-Vod-Request-Id。
需要平台协助排查问题时，请提供响应头中的 X-Vod-Task-Id。