错误码

对话补全、向量与模型列表接口的错误体与 OpenAI 格式兼容，另带 request_id 与 details。/messages 使用 Anthropic 格式，见 Anthropic 格式的错误体。

{
  "error": {
    "message": "请求过于频繁，请稍后再试",
    "type": "rate_limit_error",
    "code": "rate_limited",
    "scirouter_code": "RATE_LIMITED",
    "request_id": "req_88a1",
    "details": { "retry_after_seconds": 12 }
  }
}

返回 details.retry_after_seconds 时，响应头 Retry-After 必定取相同的值。

报障时提供 request_id，平台按它定位单次调用。控制台请求日志可按 request_id 查到对应记录，详情页的「复制报障信息」汇总排障所需的全部信息，见可观测性。

按指数退避重试；响应带 Retry-After 时按其等待。重试须设置次数上限。

重试不改变结果，须先修改请求或设置。

validation_failed 的触发条件：

• 请求体不是 JSON 对象、字段类型错误、缺少 model、messages 为空、stop 类型错误；
• max_tokens 超过模型或套餐的单次上限（details.limit）；
• 输入的 token 估算超过套餐的每分钟上限：details.reason 为 plan_tpm_exceeded，见 HTTP 400 的 details.reason；
• metadata、托管工具声明或缓存相关请求头写法错误；
• Idempotency-Key 超长；
• 上游拒绝请求，而平台未识别是哪种语义：details.source 为 upstream，带 provider_error。已识别语义的归入 context_window_exceeded、unsupported_param、content_filtered。

context_window_exceeded 的两种来源：

• 平台发出前估算得出：带 details.limit、details.estimated、details.max_tokens；
• 上游报告：details.semantic 为 context_window_exceeded，厂商文案含数字时才带 limit 与 estimated。

unsupported_param 的触发条件：

• 契约类参数在该模型的所有线路上都无法带到（details.param、details.cause）；
• 上游明确拒绝某个参数，而平台无法去掉它（details.semantic 为 unsupported_param，code 为 unsupported_parameter 或 unsupported_value）；
• 请求含只能原样转发的内容，而没有可转发的线路（details.reason 为 unsupported_content，details.unsupported_content 列出这些内容）；
• 远程图片无法取回（details.reason 为 media_fetch_failed）。

type 按状态码映射，与 OpenAI 的惯例一致。程序分支使用 code。

平台将上游错误中的三种常见语义归为固定的 code：context_window_exceeded（上下文超长）、unsupported_param（参数不支持）、content_filtered（内容审核）。三者均为 400，不可重试，须修改请求。错误体分两层：

• 平台码在 error.scirouter_code（OpenAI 格式）或 error.code（Anthropic 格式，小写）中；details 照常带 param、limit、estimated、semantic、provider_error。
• code 只取原厂可识别的值，供现有客户端使用：Claude Code 按 prompt is too long 中的两个数字裁剪历史、按 exceed context limit 调小 max_tokens；Codex 仅在 response.failed 中出现 context_length_exceeded 时压缩对话；不少 OpenAI 兼容客户端按 context_length_exceeded 或 unsupported_parameter 分支。
• 无法带到线路上的提示类参数默认由网关去掉并留痕，不返回 400，见参数如何被处理。
• 上下文超长通常由平台在发出前估算得出（带 details.estimated），此时不预扣、不占名额。
• 上游不支持某个参数时，平台先尝试去掉该参数后重发（响应头 X-SciRouter-Param-Actions 中记为 healed）。返回 400 表示该参数无法去掉，或没有可换的线路。

/messages 与 /messages/count_tokens（以及带 anthropic-version 请求头的 /models）返回 Anthropic 格式的错误体，鉴权失败时也是如此，Anthropic SDK 可直接识别：

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "…",
    "code": "model_unavailable",
    "details": { "reason": "endpoints_busy" }
  },
  "request_id": "req_88a1"
}

状态码、code 与 details 与可重试的错误、不可重试的错误两张表完全相同（error.code、error.details 为扩展字段），request_id 位于顶层。error.type 按状态码映射，平台策略类拒绝例外，取 policy_blocked：

policy_blocked 覆盖下列 code。状态码保持各自的 401、402、403、404、422 或 429，并带 x-should-retry: false。修改请求或重试均无效，需人工处理；Claude Code 直接展示该错误，不重试。

模型暂时不可用时仍返回 503，不使用 Anthropic 的 529。Anthropic SDK 对 5xx 自动重试，带 x-should-retry: false 的除外。程序分支使用 error.code。

以下两项遵循 Claude Code 的网关约定：

• 能力类拒绝带固定标记：平台自身拒绝、且客户端关闭对应能力即可恢复的 400，在 message 末尾追加 capability_rejected: <class>，details.capability_rejected 取相同值。Claude Code 收到后关闭该能力并重发。class 取值见下表。
• 转发上游的 4xx 时，厂商原文保留在 message 中（前缀为「上游拒绝了请求：」），按子串匹配的客户端不受影响。

model_unavailable 同时覆盖「暂时繁忙」与「本次请求在该模型上无法完成」两类情况，以 details.reason 区分。details.reason 为固定的英文码，可用于程序分支。

不带 Retry-After 的 503 重试无效。 这类响应带 x-should-retry: false。OpenAI 与 Anthropic 的官方 SDK 以及 Claude Code 先读取该响应头，值为 false 时停止自动重试并直接返回错误；自行实现的重试逻辑也应读取该响应头。

请求含只能原样转发的内容、而没有可转发的线路时，返回 400 unsupported_param（details.reason 为 unsupported_content），不再归入 no_capable_endpoint。503 只用于等待后可恢复或更换模型可解决的情况。

validation_failed 多数情况下不带 details.reason，按 message 与 param 处理即可。下列情况带固定的 reason，适用的接口见各行：

unsupported_param 与 context_window_exceeded 的 details.reason 同样固定：

rate_limited 与另外两个配额类 code 的区别：

每分钟 token 数在请求开始时按「输入估算 + 输出预留」计入，输出预留是 max_tokens 与平台设定值中的较小者；请求结束后按实际用量多退少补，实际输出超过预留的部分补记。因此 max_tokens 写得大不会被提前拒绝，但同一分钟里的长输出会让后续请求收到 429。

按 code 与 details 分支，不只看状态码。等待时长以 Retry-After（或 details.retry_after_seconds）为准。

网关内置故障转移：默认在上游超时、返回 5xx 或被上游限流时，自动转到该模型的下一条可用线路，最多再转 2 次，总耗时不超过 60 秒（各模型可单独配置）。只有一条线路的模型、已开始输出的流式请求不做转移。

因此调用方收到 5xx 时，网关通常已尝试过其他线路；尝试次数见成功响应中的 scirouter.attempts 或响应头 X-SciRouter-Attempts。客户端的重试使用指数退避，不立即重发。

非流式请求重试时带同一个 Idempotency-Key，首次请求实际已成功时不会重复扣费。前提是首次请求未被客户端先断开：客户端断开的请求由服务端取消且不保存结果，见缓存与幂等。

官方 SDK 默认自动重试 429 与 5xx，不区分 code，见 SDK 与框架「重试与超时」。

流式响应可能在已输出部分内容之后出错。此时 HTTP 状态码已是 200，错误以带 error 字段的分片出现在流中，随后流直接结束，不再发送 data: [DONE]：

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"这段序列的"}}]}

data: {"error":{"message":"上游模型服务响应超时","type":"upstream_error","code":"upstream_timeout","request_id":"req_88a1","details":{"timeout":"idle"}}}

只检查 HTTP 状态码会把截断的回答当作完整回答。三种格式的流式结束标志与出错方式：

未收到正常结束标志即结束的流，一律按失败处理。

上下文超长例外：/responses 的流式调用无论在开流前还是开流后判定超长，均返回 HTTP 200 与 response.failed 事件（response.error.code 为 context_length_exceeded），Codex 只在收到该事件时压缩对话。非流式调用仍返回 HTTP 400。

流中错误帧的 code 只取原厂可识别的值，平台码仍在 scirouter_code：

请求 /v1 下不存在的路径（如 /v1/completions）时返回 404，错误体为站内接口的格式（大写的 NOT_FOUND），与本页其他错误体不同。官方 SDK 同样抛出「未找到」异常。出现该错误时检查请求路径与 base_url，确认没有多写或少写一段 /v1。