错误码
Last updated: Nov 4, 2026
大模型请求可能返回两类错误：API 调用错误和模型原生错误。两类错误的响应结构不同。
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，或请求 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 服务或模型服务暂时不可用 |
若API调用本身无错误，并且成功把请求发送给模型，则发生的错误将会把模型原生响应返回给用户。模型原生错误遵循所调用模型协议的错误结构，不使用上面的 requestId/code/message 结构。常见响应格式如下：OpenAI、Anthropic、Gemini
{
"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 通常为数字。
- 先判断响应体是否包含整数类型的顶层
code > 0。存在时，按 API 服务错误处理。 - 否则按当前调用的 OpenAI、Anthropic 或 Gemini 原生协议解析错误体。
- 对于http状态码：
- 对
400、401、403、404、405和409，应先修正客户端请求、权限或调用路径。 - 对
429，降低请求速率或并发量后再发起新请求。 - 对
500、502和503，可使用退避策略有限重试，并为重试请求生成新的请求头X-Vod-Request-Id。
- 对
需要服务端研发人员帮助排查问题时，请记录并提供X-Vod-Request-Id或X-Vod-Task-Id。