OctaRouter 通过 octafuse-gateway 转发推理请求。错误分为两类：到达上游前的网关校验，以及 转发后的上游响应（含故障转移）。
透传原则： 一旦请求到达上游供应商，HTTP 状态码与 JSON 响应体遵循该供应商的官方 API——不是自定义的 OctaRouter 封装。网关自身生成的错误使用简单的
{ "error": "..." }字符串。
网关生成的错误
这些错误发生在 任何上游调用之前（鉴权、模型查找、路由、预算）。响应体始终为：
{ "error": "message" }
| 状态 | 何时出现 |
|---|---|
| 401 | 缺少 API Key、Key 无效或已撤销 |
| 403 | 预付费预算耗尽（Budget exceeded） |
| 404 | 当前网关部署找不到该模型 ID（Model not found） |
| 400 | JSON 非法、缺少 model，或请求的路由组没有可用路由 |
| 502 | 该协议没有可用上游路由、路由失败，或连接供应商网络错误（Upstream request failed 等） |
说明：
- 预算超限返回 403，不是 402。
- 404 表示网关不认识该模型 ID——不是上游“模型不存在”错误。
- 修复时请检查 API Key、账户余额、模型 页上的模型 ID，以及请求体形状。
上游错误（透传）
路由成功后，网关会把请求转发给一个或多个上游供应商（同一路由组内按优先级故障转移）。
| 行为 | 细节 |
|---|---|
| 上游非 2xx（含 429） | 尝试组内下一条路由；若全部失败，返回 最后一次上游响应原样（状态码 + 响应体） |
| 网络 / fetch 失败 | 尝试下一条路由；若全部失败，网关返回 502，body 为 { "error": "Upstream request failed" } |
| 响应体 | 供应商原生 JSON——例如 OpenAI { "error": { "message", "type", "code" } }、Anthropic { "type": "error", "error": { ... } }、Gemini 的 Google 风格 JSON |
请求校验、流式、工具错误等 API 语义，请遵循你所用协议的 官方文档（链接见 API 协议）。
限流（429）
网关 不会 自行施加 API 限流，也不会自己返回 429。
429 来自 上游供应商，表示你超出了他们的配额或吞吐。如果故障转移路由也返回 429，你会原样收到最后一个供应商的 429 响应。
客户端处理 429 的建议：
- 使用带抖动的指数退避
- 降低并发或请求速率
- 查看上游错误体中的重试提示（
Retry-After、errorcode等）
OctaRouter 不单独定义的内容
OctaRouter 文档不会维护一份独立的上游错误码目录。请求转发之后，以供应商响应为准。
成功响应同样按供应商原生形态透传（网关侧会做模型映射、注入供应商凭证等改写——见 API 协议）。