入门错误

错误

错误以 JSON 形式返回,状态码为 4xx 或 5xx。错误格式遵循端点所用的协议,因此 OpenAI 和 Anthropic SDK 会抛出各自常规的异常类。只有一种情况不同:非流式请求运行满 90 秒后,之后发生的错误会出现在状态码为 200 的响应体中(见长时间请求)。

错误码

错误码状态码触发条件
invalid_api_key401API 密钥缺失、格式错误、未知、已撤销或已过期。过期密钥的错误消息会注明其过期日期。
account_suspended403账户已被暂停。暂停结束前,该账户的所有密钥都会被拒绝;请联系支持。
account_banned403账户已被封禁。其密钥均已撤销,剩余额度作废。
card_network_blocked403银行卡充值被拒绝:请求来自 VPN、Tor 或数据中心网络。
card_account_risk403银行卡充值被拒绝:Stripe 的欺诈筛查将该账户评为最高风险,因此该账户无法使用银行卡充值。加密货币充值仍可正常使用。
model_not_found404model ID 不是已启用的模型。用 GET /v1/models 列出可用的 ID。
unsupported_content400请求包含模型不接受的部分:向 input_modalities 不含图像或视频的模型发送了图像或视频部分;视频不是 https:// URL(包括 base64 视频),或图像 URL 不是 https://、http:// 或 data:;或者包含音频或文件部分(所有模型都不接受)。
content_policy_violation400请求被自动安全检查拦截。
stateless_only400/v1/responses 请求设置了 previous_response_id 或 background: true。改为在 input 中发送完整对话,并且不要设置 background。
invalid_request400请求体未通过校验(例如 /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_balance402你的余额不足以支付预估输入加上至少 256 个 token 的输出预算。请充值。
key_spend_cap_reached402本次请求的预扣金额,加上该密钥的已结算消费和其他进行中的请求,将超过其每日、每月或累计消费上限。
rate_limit_exceeded429该密钥或账户本分钟内的请求过多;账户的并发请求过多;账户的大体积上传占用了过多的进行中请求体额度;或者(试用账户)同一网络在一小时内有超过 2 个试用账户发送请求。每分钟限制和试用网络限制会返回 Retry-After。
capacity_exhausted429该模型的所有副本在 30 秒的重试期间一直繁忙(试用账户不重试,立即失败),或者网关短暂满载或正在重启(状态码 503)。等待 Retry-After 指定的秒数。完全没有服务容量的模型会改为返回 model_unavailable。不会扣费。
model_unavailable503该模型当前没有服务容量,例如正在更换其 GPU。对所有账户,请求都会立即失败,不会重试。Retry-After 给出我们再次检查该模型之前的秒数;届时重试,或者改用其他模型。不会扣费。
safety_unavailable503安全检查超时或失败,因此请求被拒绝,而不是未经检查就发送出去。请稍后重试。
card_network_check_unavailable503由于网络检查暂时不可用,银行卡充值被拒绝;请重试,或使用加密货币支付。
upstream_error502模型后端出错,或者请求因达到 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 是上表中的错误码之一。例如:

json
{
  "error": {
    "type": "rate_limit_error",
    "code": "capacity_exhausted",
    "message": "All model replicas are busy. Retry shortly."
  }
}

Anthropic 格式

用于 /v1/messages。该格式没有 code 字段,因此要读取 HTTP 状态码和 error.type。例如:

json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required."
  }
}

各状态码对应的错误类型

状态码OpenAI error.typeAnthropic error.type
400invalid_request_errorinvalid_request_error
401authentication_errorauthentication_error
402insufficient_quotabilling_error
403permission_errorpermission_error
404not_found_errornot_found_error
408invalid_request_errorinvalid_request_error
413invalid_request_errorrequest_too_large
429rate_limit_errorrate_limit_error
500, 502, 503api_errorapi_error

响应头

  • 每个响应都带有 x-request-id,包括错误响应。联系支持时附上它。
  • Retry-After(单位为秒)随以下错误返回:capacity_exhausted;model_unavailable(距我们再次检查该模型的秒数,最多 15);按分钟计和按试用网络计的 rate_limit_exceeded;以及 503 upstream_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,并在生成过程中看到输出。但避免超时并不需要它。