错误
错误以 JSON 形式返回,状态码为 4xx 或 5xx。错误格式遵循端点所用的协议,因此 OpenAI 和 Anthropic SDK 会抛出各自常规的异常类。只有一种情况不同:非流式请求运行满 90 秒后,之后发生的错误会出现在状态码为 200 的响应体中(见长时间请求)。
错误码
| 错误码 | 状态码 | 触发条件 |
|---|---|---|
invalid_api_key | 401 | API 密钥缺失、格式错误、未知、已撤销或已过期。过期密钥的错误消息会注明其过期日期。 |
account_suspended | 403 | 账户已被暂停。暂停结束前,该账户的所有密钥都会被拒绝;请联系支持。 |
account_banned | 403 | 账户已被封禁。其密钥均已撤销,剩余额度作废。 |
card_network_blocked | 403 | 银行卡充值被拒绝:请求来自 VPN、Tor 或数据中心网络。 |
card_account_risk | 403 | 银行卡充值被拒绝:Stripe 的欺诈筛查将该账户评为最高风险,因此该账户无法使用银行卡充值。加密货币充值仍可正常使用。 |
model_not_found | 404 | model ID 不是已启用的模型。用 GET /v1/models 列出可用的 ID。 |
unsupported_content | 400 | 请求包含模型不接受的部分:向 input_modalities 不含图像或视频的模型发送了图像或视频部分;视频不是 https:// URL(包括 base64 视频),或图像 URL 不是 https://、http:// 或 data:;或者包含音频或文件部分(所有模型都不接受)。 |
content_policy_violation | 400 | 请求被自动安全检查拦截。 |
stateless_only | 400 | /v1/responses 请求设置了 previous_response_id 或 background: true。改为在 input 中发送完整对话,并且不要设置 background。 |
invalid_request | 400 | 请求体未通过校验(例如 /v1/messages 缺少 max_tokens;n 不为 1;/v1/completions 的 prompt 数组中超过 4 个提示词;在没有优先级档位的模型上设置 service_tier: "priority";工具类型不是 function(在 /v1/responses 上还可以是 custom 和 namespace);或对没有文本补全端点的模型调用 /v1/completions),请求体未能及时接收(状态码 408)或超过 16 MiB(状态码 413),或者被模型拒绝,例如提示词超出上下文窗口,或图像数量超过模型上限。模型拒绝时保留其自身的 4xx 状态码和消息。 |
insufficient_balance | 402 | 你的余额不足以支付预估输入加上至少 256 个 token 的输出预算。请充值。 |
key_spend_cap_reached | 402 | 本次请求的预扣金额,加上该密钥的已结算消费和其他进行中的请求,将超过其每日、每月或累计消费上限。 |
rate_limit_exceeded | 429 | 该密钥或账户本分钟内的请求过多;账户的并发请求过多;账户的大体积上传占用了过多的进行中请求体额度;或者(试用账户)同一网络在一小时内有超过 2 个试用账户发送请求。每分钟限制和试用网络限制会返回 Retry-After。 |
capacity_exhausted | 429 | 该模型的所有副本在 30 秒的重试期间一直繁忙(试用账户不重试,立即失败),或者网关短暂满载或正在重启(状态码 503)。等待 Retry-After 指定的秒数。完全没有服务容量的模型会改为返回 model_unavailable。不会扣费。 |
model_unavailable | 503 | 该模型当前没有服务容量,例如正在更换其 GPU。对所有账户,请求都会立即失败,不会重试。Retry-After 给出我们再次检查该模型之前的秒数;届时重试,或者改用其他模型。不会扣费。 |
safety_unavailable | 503 | 安全检查超时或失败,因此请求被拒绝,而不是未经检查就发送出去。请稍后重试。 |
card_network_check_unavailable | 503 | 由于网络检查暂时不可用,银行卡充值被拒绝;请重试,或使用加密货币支付。 |
upstream_error | 502 | 模型后端出错,或者请求因达到 10 分钟时间上限、模型连续 2 分钟没有输出或重启而被中止。意外的内部故障会以状态码 500 返回此错误码;我们这一侧的短暂中断或重启会以状态码 503 返回,并附带 Retry-After;后端故障会以状态码 502 返回;以上均发生在发送任何响应之前。时间上限要到之后才会触发:它们会结束流式输出,而运行超过 90 秒的非流式响应已经以状态码 200 发出,因此这时此错误(无论由时间上限还是其他原因引起)会出现在响应体中,不带 Retry-After(见“长时间请求”)。如果模型尚未生成任何输出,则不扣费,重试该请求即可。一旦已生成输出,请求将按预估输入加上故障或中止前已生成的输出计费。客户端主动断开连接时永远不会收到此错误;即使没有生成任何输出,也会按预估输入计费。 |
content_policy_violation 拦截哪些内容,由《可接受使用政策》规定。
OpenAI 格式
用于 /v1/chat/completions、/v1/responses、/v1/models 和 /v1/balance。code 是上表中的错误码之一。例如:
{
"error": {
"type": "rate_limit_error",
"code": "capacity_exhausted",
"message": "All model replicas are busy. Retry shortly."
}
}Anthropic 格式
用于 /v1/messages。该格式没有 code 字段,因此要读取 HTTP 状态码和 error.type。例如:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "max_tokens is required."
}
}各状态码对应的错误类型
| 状态码 | OpenAI error.type | Anthropic error.type |
|---|---|---|
| 400 | invalid_request_error | invalid_request_error |
| 401 | authentication_error | authentication_error |
| 402 | insufficient_quota | billing_error |
| 403 | permission_error | permission_error |
| 404 | not_found_error | not_found_error |
| 408 | invalid_request_error | invalid_request_error |
| 413 | invalid_request_error | request_too_large |
| 429 | rate_limit_error | rate_limit_error |
| 500, 502, 503 | api_error | api_error |
响应头
- 每个响应都带有
x-request-id,包括错误响应。联系支持时附上它。 Retry-After(单位为秒)随以下错误返回:capacity_exhausted;model_unavailable(距我们再次检查该模型的秒数,最多 15);按分钟计和按试用网络计的rate_limit_exceeded;以及 503upstream_error(我们这边的短暂中断或重启)。
何时重试
| 错误 | 怎么做 |
|---|---|
capacity_exhausted | 等待 Retry-After 秒后重试。429 表示付费请求已重试了最多 30 秒;503 表示网关已满载或正在重启,请求从未到达模型。 |
model_unavailable | 等待 Retry-After 秒后重试:那是我们下次检查该模型的时间。由于模型没有服务容量,请求立即失败,没有重试。这种中断可能持续几分钟,如果错误持续存在,换用其他模型。 |
rate_limit_exceeded | 对于每分钟限制,等待 Retry-After 秒。对于并发限制,等你正在运行的某个请求结束后再重试。对于每个网络的试用账户数限制,等待 Retry-After 秒或充值:付费账户不受此限制。 |
safety_unavailable | 几秒后重试。安全检查采用失败即拒绝(fail closed)的策略:无法运行时,请求会被拒绝,而不是不经检查就转发。 |
upstream_error | 状态码为 503 时,等待 Retry-After 秒后重试。其他情况(包括错误出现在 200 响应体中时),使用指数退避重试。 |
insufficient_balance, key_spend_cap_reached | 充值,或提高上限、等到上限周期结束。提前重试没有用。 |
| 其他 4xx | 修正请求。原样重试会返回相同的错误。 |
未产生输出的失败请求不收费,包括因时间限制或重启而停止的请求。唯一的例外是客户端断开连接:即使没有生成任何输出,也会按估算的输入收费。模型已生成输出后才失败或被停止的请求,收取估算的输入加上结束前已生成的输出。见请求如何计费。
长时间请求
非流式响应是一个 JSON 对象,在模型生成完毕时就绪。如果它在请求到达后 90 秒内就绪,就会照常发送:结果或错误,带有各自的状态码和响应头。
90 秒后仍未就绪的响应会在此时开始发送,以保持连接:先发出状态码 200 和 Content-Type: application/json(以及 x-request-id),响应体以一个换行符(\n)开头,之后每 15 秒再发送一个。结果就绪后,JSON 对象随之发出,响应结束。JSON 解析器会跳过值前面的空白字符,因此 OpenAI 和 Anthropic SDK、JSON.parse、json.loads 和 response.json() 都能照常读取。非流式请求由此获得完整的 10 分钟时间限制。
状态码一旦为 200,错误就无法再改变它。此后发生的错误(10 分钟时间限制、模型 2 分钟无输出、后端故障或重启)会以常规错误对象的形式出现在 200 响应体中:OpenAI 格式,或在 /v1/messages 上为 Anthropic 格式。此时无法附带 Retry-After 响应头。只检查状态码的客户端看不到这个错误,因此要检查响应体中是否有顶层 error 成员。计费方式与其他失败或被停止的请求相同(见上文),等待期间关闭连接视为客户端断开连接。
对于长时间的生成,使用 "stream": true 流式输出仍是不错的选择:你能更早看到最初的 token,并在生成过程中看到输出。但避免超时并不需要它。