错误处理与重试

网关的错误分两类来源：网关自己产生的和上游厂商透传回来的。 先学会一眼分清这两类，剩下的处理逻辑就都顺了。

网关错误的结构

凡是网关自己拒绝的请求，返回体都是这个形状：

{
  "code": 40101,
  "message": "api key not found",
  "error": {
    "message": "api key not found",
    "type": "gateway_error",
    "code": "40101"
  }
}

error.type 恒为 "gateway_error"——这就是区分两类错误的判据。 顶层的 code 是数字，error.code 是同一个值的字符串形式（为了兼容 OpenAI 错误体结构）。

错误码怎么读

网关错误码是 5 位数字，规则是 HTTP 状态码 + 2 位序号：

  401  01
  └┬┘  └┬┘
   │    └── 序号：同一状态码下的第几种原因
   └─────── HTTP 状态码

所以看到 42905 就知道 HTTP 是 429（限流），看到 50201 就知道是 502（上游侧）。 唯一的例外是 41301（请求体过大），它的 HTTP 状态是 413。 全部错误码见 错误码总表。

上游错误

如果请求已经成功路由到上游厂商，而厂商返回了错误，网关原样透传：状态码、 响应体结构都是厂商的原始格式，不做包装。这意味着：

• 你现有的官方 SDK 错误处理代码可以继续用，不需要改。
• 响应体里不会有 "type": "gateway_error"。
• 厂商的限流（如 OpenAI 的 429）与网关的限流（429xx）需要分开对待——见下文。

哪些能重试

限流响应头

网关返回 429 时会附带这几个头，直接照着做退避即可：

参考实现

指数退避 + 抖动 + 遵守 Retry-After，这是一个够用的骨架：

import random, time
import httpx

# 只有这几个码值得重试；其余一律直接抛给调用方
RETRYABLE = {42901, 42902, 42903, 42904, 42905, 42908, 50401, 50204, 50205}

def call_with_retry(payload, max_attempts=4):
    for attempt in range(max_attempts):
        r = httpx.post(
            "https://www.apigoto.com/v1/chat/completions",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json=payload,
            timeout=120,
        )
        if r.status_code < 400:
            return r.json()

        body = r.json()
        code = body.get("code")
        if code not in RETRYABLE or attempt == max_attempts - 1:
            raise RuntimeError(f"[{code}] {body.get('message')}")

        # 服务端给了 Retry-After 就听它的，没给就指数退避
        wait = int(r.headers.get("Retry-After", 0)) or 2 ** attempt
        # 抖动：避免一批客户端同时被限流后又同时重试，把峰值原样搬到下一秒
        time.sleep(wait + random.uniform(0, 0.5))

生产接入建议

• 日志里记 code，不要只记 message。 message 是给人看的、可能随版本调整措辞；code 是稳定契约。
• 给请求设超时。推荐读超时 120 秒起步；长文本生成或推理型模型要更长。 超时设太短的表现是「客户端报超时但账单照扣」——上游其实还在生成。
• 重试上限 3–4 次。再多不会提高成功率，只会拉长故障时的响应时间。
• 连续失败要熔断。上游整体不可用时（大量 502/504），继续打只会加剧拥塞。
• 流式请求的重试要谨慎。已经吐出部分内容的流不能简单重发——见 流式响应 里关于终止事件的判据。