错误码

这一页按代码实际行为整理；请求头、响应头、限流与余额处理等平台层面的行为见平台扩展与差异。先说两件事：

• 请求经过两层，网关（鉴权、限流、余额、请求体检查）和路由层（选上游、调上游、故障切换）。两层生成的错误形态不完全一样，而且路由层会把上游返回的状态码原样带给你。
• error.code 不可靠。网关生成的错误没有 code；路由层生成的 code 有时等于 type，有时是更细的值。分支判断请用 HTTP 状态码加 error.type，不要依赖 code。

每个响应都带 X-Request-ID 头（你自己传了就原样回显）。报问题时附上它。

怎么判断

1. 看状态码。2xx 成功；4xx 一般是请求本身的问题，不要原样重试；429、5xx 才值得重试，见重试建议。
2. 看响应体形态（见下节）。不要假设一定是 {"error": {...}}：/v1/messages 上是 Anthropic 风格的对象，原生入口的创建阶段错误是各自厂商的格式。
3. 流式请求要看流本身。HTTP 已经返回 200 之后的失败只会出现在流里，状态码不会变，见流式中途失败。

错误结构

OpenAI 风格（默认）

/v1/chat/completions、/v1/responses、/v1/embeddings、图像、语音等入口，以及网关层的所有错误，都是这个形态：

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: foo-1"
  }
}

没有单独标出出错参数的 error.param，出错的字段看 message。

Anthropic 风格（/v1/messages 与 /v1/messages/count_tokens）

{
  "type": "error",
  "error": { "type": "invalid_request_error", "message": "max_tokens is required and must be > 0" }
}

这两个入口上，网关层错误（鉴权、余额、限流、请求体过大、组织停用等）和路由层错误都是这一种形态，type 取 Anthropic 官方的名称：400 为 invalid_request_error，401 为 authentication_error，402 为 billing_error，403 为 permission_error，404 为 not_found_error，413 为 request_too_large，429 为 rate_limit_error，503 为 overloaded_error（当错误本身已是某个官方名称时保持不变），504 为 timeout_error，其余 5xx 为 api_error。

组织或团队停用

组织、团队被停用，或 Key 没有归属组织时，状态码是 403，响应体与其它网关错误一样是标准错误对象，形态随入口而定（/v1/messages 为 Anthropic 风格，其余入口为 OpenAI 风格，Gemini 入口为 Google 风格），type 为 permission_error，message 为 organization suspended、team suspended 或 API key is not attached to an organization。

原生入口的创建阶段错误

原生入口只有平台自己做的参数校验用厂商原生格式，其余错误（见下节"入口差异"）仍是 OpenAI 风格。

状态码

路由层返回的上游错误，来自最后一次尝试的那个上游：平台会先切换上游，全部失败后把最后一个上游的状态码和说明返回给你。所以同一个 401、402、403，既可能是网关对你的 Key 的判定，也可能是上游对平台账号的判定。网关的 401 文案是固定的几句（见上表），402 的 type 固定为 insufficient_quota（/v1/messages 上为 billing_error）；不符合这些特征的，是上游透传，见下节。

503 的几种来源

这几种都值得重试，但只有第一种明确给出了等待时间。

type 取值

网关生成

路由层生成

no_upstream_available 与 upstream_cooling_down 两个错误码于 2026-10-19 更名，旧名 no_suppliers_available / all_vendors_cooling_down 含义相同；若你的客户端按旧码判断，请同时匹配新旧两个名字。

上游错误经路由层透传

状态码取上游的，message 取上游的文案（会去掉请求 ID、内部端点 ID 等标识）。type 取决于入口和上游类型：

context_length_exceeded 和 content_policy_violation 只在 embeddings、rerank 上出现。对话类入口遇到上下文超长或内容审核，你收到的是 400 加 api_error 或 invalid_request_error，原因在 message 里。

各入口的差异

视频与异步任务要注意：

• 创建请求成功只表示任务已提交，HTTP 状态是 200。任务后来失败时，轮询接口仍返回 200：百炼入口里 output.task_status 为 FAILED，原因在 output.code 和 output.message；方舟、MiniMax 入口返回上游任务体，status 为 failed，错误字段是上游自己的。
• 轮询时任务 ID 无效或过期，用的是原生入口各自的 404 格式；轮询时上游调用本身出错，则是 OpenAI 风格的 500 或 502。
• /v1/videos、/v1/videos/generations 已下线，返回 404，code 为 endpoint_retired。视频只在各模型的原生入口提供。

GET /v1/responses/{id} 通过响应 ID 找回创建它的上游。ID 无法解码时是 400，找不到上游是 404（type: not_found）。DELETE /v1/responses/{id} 和 POST /v1/responses/{id}/cancel 不需要请求体，也不需要 model，网关直接放行到后端；它们不产生费用，余额耗尽时同样可用。

流式中途失败

流一旦开始，HTTP 状态已经是 200，之后的失败只能写进流里。三种情况：

• 上游中途报错、连接中断、流被截断（没有收到结束事件就结束了）、或默认 4 分钟没有任何数据：按上表的入口格式发出一个错误事件，然后结束流。type 是上游的错误类型，网络层或截断统一为 server_error。
• 组织余额在流进行中耗尽：网关切断流，并写入 data: {"error":{"type":"insufficient_quota","message":"balance exhausted"}} 和 data: [DONE]。这一帧在所有流式入口上都是这个 OpenAI 风格，包括 /v1/messages。
• 你主动断开：没有任何错误事件。

处理方式：把"没有收到正常结束标志"当成失败。Chat Completions 是最后一个 chunk 没有 finish_reason 或出现了 error 帧，Anthropic 是没有 message_stop，Responses 是没有 response.completed。中途失败时，已经生成的部分仍按上游实际用量计费。

在收到第一个字节之前失败，平台会先自动切换上游，成功就正常返回，全部失败才返回一个带状态码的 JSON 错误。

重试建议

import random, time

RETRYABLE = {408, 429, 500, 502, 503, 504}

def call_with_retry(send, tries=4):
    for i in range(tries):
        resp = send()
        if resp.status_code not in RETRYABLE or i == tries - 1:
            return resp
        wait = float(resp.headers.get("Retry-After", 2 ** i))
        time.sleep(wait + random.random())

重复调用与重复计费

• 平台没有幂等键，也不会按请求内容去重。
• 一次请求在平台内部切换上游，只有最终成功的那一次会计费，失败的尝试不计费。你看到的是一次成功或一次错误。
• 你自己重试则是新的请求。如果上一次其实已经成功、只是响应没到你手里（客户端超时、连接被切断），重试会产生第二次生成和第二次计费。对话类请求副作用有限，可以接受；视频创建不能这样重试：创建请求遇到超时、502 或连接中断时，先确认任务有没有建出来，再决定是否重新创建，否则会出现两个任务、两份费用。
• 流式请求中途失败不要整体重试成"同一次生成"，已输出的部分已经计费，重试从头再来会再计费一次。需要续写就把已收到的内容放进上下文发新请求。
• 非流式请求有两个相关的时间限制：网关等不到响应头 120 秒就断开并返回 502；路由层调用上游的总时限是非流式 10 分钟、流式 5 分钟。生成时间可能超过两分钟的请求请用 stream: true。