开发者文档 错误码
错误码
网关错误沿用你调用的协议格式;按状态码和错误类型排查,联系维护人员时带上请求编号。
格式
网关自己返回的错误跟着你调用的接口走,与背后是哪条上游线路无关。响应类型为 application/json,说明文字是英文,文案可能调整,程序判断请用状态码和类型字段。错误体里没有请求编号,请看响应头 X-Request-Id。
| 接口 | 错误格式 | 判断字段 |
|---|---|---|
/v1/chat/completions、/v1/responses、/v1/embeddings、/v1/images/generations、/v1/images/edits、/v1/models | OpenAI | error.type、error.code |
/v1/messages、/v1/messages/count_tokens | Anthropic | error.type |
/v1beta/models/... | Gemini | error.status |
/minimax/v2/... | MiniMax 视频 | error.type |
/minimax/v1/t2a_v2 | MiniMax 语音 | base_resp.status_code |
/ark/api/v3/... | 火山方舟 | error.code |
/v1/models 请求带 anthropic-version 头时返回 Anthropic 格式。
OpenAI 格式:
{
"error": {
"code": "invalid_api_key",
"message": "invalid API key",
"param": null,
"type": "invalid_request_error"
}
}Anthropic 格式:
{
"error": {
"message": "invalid API key",
"type": "authentication_error"
},
"type": "error"
}其他格式:Gemini 返回 error.code(HTTP 状态码)、error.message 和 error.status;MiniMax 视频返回顶层 type(值为 error)以及 error.type、error.message 和字符串形式的 error.http_code;MiniMax 语音返回 base_resp.status_code 和 base_resp.status_msg;火山方舟返回 error.code、error.message、error.param 和 error.type,其中 error.type 是去掉空格的 HTTP 状态名,例如 TooManyRequests。
网关返回的状态码
| 状态 | 原因 | OpenAI type · code | Anthropic type | Gemini status |
|---|---|---|---|---|
| 400 | 请求体读不出来或缺少模型,用了网关不支持的功能,或模型不在这个接口提供 | invalid_request_error · null | invalid_request_error | INVALID_ARGUMENT |
| 401 | 缺少密钥、密钥无效或已过期 | invalid_request_error · invalid_api_key | authentication_error | UNAUTHENTICATED |
| 402 | 密钥所属的预算已用完 | insufficient_quota · insufficient_quota | billing_error | RESOURCE_EXHAUSTED |
| 403 | 密钥的模型范围不含这个模型 | invalid_request_error · model_not_allowed | permission_error | PERMISSION_DENIED |
| 404 | 模型不存在 | invalid_request_error · model_not_found | not_found_error | NOT_FOUND |
| 413 | 请求体超过 32 MiB | invalid_request_error · request_too_large | request_too_large | INVALID_ARGUMENT |
| 429 | 模型的所有上游线路都没有余量,带 Retry-After | requests · rate_limit_exceeded | rate_limit_error | RESOURCE_EXHAUSTED |
| 502 | 连不上上游,上游响应无法读取或转换,或上游拒绝了网关的账号 | server_error · upstream_failed | api_error | UNAVAILABLE |
| 503 | 网关还没加载模型目录,或模型、视频任务的上游暂时不可用 | server_error · service_unavailable | api_error | UNAVAILABLE |
| 504 | 上游没有按时响应 | server_error · upstream_timeout | timeout_error | DEADLINE_EXCEEDED |
MiniMax 与火山方舟接口的状态码含义相同,类型字段如下。视频任务不存在或无权访问时也返回 404,取消已经开始生成的任务返回 400。
| 状态 | MiniMax 视频 error.type | MiniMax 语音 base_resp.status_code | 火山方舟 error.code |
|---|---|---|---|
| 400 | bad_request_error | 2013 | InvalidParameter |
| 401 | authorized_error | 1004 | AuthenticationError |
| 402 | insufficient_balance_error | 1008 | AccountOverdueError |
| 403 | permission_error | 1004 | AccessDenied |
| 404 | not_found_error | 2013 | 模型为 InvalidEndpointOrModel.NotFound,任务为 ResourceNotFound |
| 413 | bad_request_error | 2013 | RequestTooLarge |
| 429 | rate_limit_error | 1002 | ServerOverloaded |
| 502 | server_error | 1033 | InternalServiceError |
| 503 | server_error | 1000 | ServiceUnavailable |
| 504 | server_error | 1001 | RequestTimeout |
路径或请求方法不对时返回的 404 不是 JSON,请检查基础地址和路径。
上游返回的错误
表外的状态码和错误码来自上游:
- 上游返回
400、422这类请求本身的错误时,网关不换线路,原样返回状态码和响应体。 - 上游返回
401、402、403、404、408、429或5xx时,网关先换线路重试,都失败时返回最后一次的错误。其中401、402、403说明上游不接受网关的账号,与你的密钥无关,网关改为返回502。 - 网关转换了协议时(响应头带
X-Mosshub-Translated),上游错误会改写成你调用的协议格式。 - 上游响应头只透传
Content-Type、Retry-After、Retry-After-Ms、X-Should-Retry和Anthropic-Ratelimit-Unified-*。 - MiniMax 语音的上游业务错误可能以
200返回,错误在base_resp.status_code。
流式响应中途出错
流式响应开始后,状态码已经是 200。之后出错时,网关这样结束响应:
| 接口 | 结束方式 |
|---|---|
/v1/chat/completions | 直接结束,没有 data: [DONE] |
/v1/responses | response.failed 事件 |
/v1/messages | error 事件 |
/minimax/v1/t2a_v2 | 一条 base_resp.status_code 为 1033 的事件 |
报障编号
| 编号 | 位置 | 用途 |
|---|---|---|
X-Request-Id | 每个响应的响应头 | 服务端为每个请求生成,客户端不能指定;调用记录的请求编号就是它,联系维护人员时提供它和请求时间 |
X-Client-Request-Id | 你发送的请求头,可选 | 你自己的关联编号,最长 128 个可打印 ASCII 字符,不合规时忽略;随调用记录保存,不用于去重 |
| 上游请求 ID | 「我的用量」的调用详情 | 上游给这次调用的编号,用于和上游对账 |
怎么处理
实际可调用的模型、授权与价格以控制台为准。
页面字体:MiSans(小米,依《MiSans 字体知识产权许可协议》使用);Google Sans Flex(SIL Open Font License 1.1)。
页面字体:MiSans(小米,依《MiSans 字体知识产权许可协议》使用);Google Sans Flex(SIL Open Font License 1.1)。