错误参考

网关模型入口（OpenAI / Anthropic / Gemini 三协议）的所有失败响应都遵循统一 的错误信封：错误体里携带稳定的 reason 标识，HTTP 状态、错误类型和是否可 重试都由该 reason 在导出时的内核表决定。本页由 lobsterpool/scripts/gen-error-reference.mjs 从 OpenAPI 工件的 LlmErrorReference 组件生成，请勿手改表格；重新导出 OpenAPI 工件后重跑 生成器即可更新。

三协议错误体

三种协议的错误体形状不同，但携带同一个 reason（Anthropic / Gemini 形状 见各自信封；下例为同一失败在三种协议下的渲染）：

OpenAI 协议 — {"error": { … }}：

{
  "error": {
    "message": "上游服务暂时不可用，请稍后重试。",
    "type": "server_error",
    "param": null,
    "code": "upstream_server_error",
    "reason": "LLM_UPSTREAM_SERVER_ERROR",
    "request_id": "0197ffffffffffffffffffffffffffff"
  }
}

Anthropic 协议 — {"type": "error", "error": { … }, "request_id": …}：

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "上游服务暂时不可用，请稍后重试。",
    "reason": "LLM_UPSTREAM_SERVER_ERROR"
  },
  "request_id": "0197ffffffffffffffffffffffffffff"
}

Gemini 协议 — {"error": { … }}：

{
  "error": {
    "code": 502,
    "message": "上游服务暂时不可用，请稍后重试。",
    "status": "UNAVAILABLE",
    "details": []
  }
}

如何判断该怎么处理

1. HTTP 状态：由 reason 查下表得出，三种协议一致（Gemini 错误体的 code 字段与响应 HTTP 状态相同）。
2. 是否重试：看响应头 x-should-retry，与下表「是否可重试」列一致。 为 true 时按同一段中的说明重试；为 false 时重试不会改变结果。
3. 调用方怎么做：由 remediation_owner（谁来处理）与 should_retry 推出：
   • client → 修改请求；
   • upstream 且可重试 → 稍后重试；
   • platformConfig → 联系管理员检查模型供应商或路由配置；
   • transport → 按请求是否携带幂等键决定（带幂等键可安全重试）。

连通失败分层分类（ConnectivityFailureKind）

网关数据面、通道根探活、模型供应商测试、MCP 发现、出口代理测试及 zenova doctor --target 对上游建连失败统一采用七类分层归因（与 ConnectivityFailureKind 枚举一一对应）：

请求标识

排查时先取请求标识：响应头 x-request-id 是网关侧的逻辑请求 id， OpenAI / Anthropic 错误体内的 request_id 字段与其相同。向管理员反馈时 附上该值即可定位完整调用记录。

流式错误

流式请求在开始输出后遇到失败时，网关会发送一条流内错误帧（与所选协议的 错误体同形），随后正常结束流。已输出的内容与用量照常计费和展示； reason 仍可按下表解读。

reason 全表（277 项）

下表按内核导出顺序列出数据面可能出现的全部 reason。「渲染字段」列为 OpenAI 协议的渲染结果，Anthropic / Gemini 协议的 type / status 由同一 reason 投影。