大模型 API 报错对照:401 / 429 / 超时 / 超长一次排完

先给结论:大模型接口的报错基本就六类——401/403(Key 或权限)、429(限流)、超时、上下文超长、流式中止、以及网关自己返回的 5xx。其中 401 和 429 占绝大多数,且大多不是「模型坏了」,而是 Key、额度或重试策略的问题。先按下面的对照表定位类型,再按第六节的六步顺序排,比盲目改代码快得多。

一、先分清「谁报的错」

  • 你的代码报的:连接失败、JSON 解析崩、超时——多半是网络或参数问题。
  • 厂商网关报的:带状态码和 JSON 错误体(如 401、429、400)——看 error.message 最直接。
  • 中间层报的:用了网关 / 代理 / 本地 Ollama(见 D14),错误可能是它包装过的,别只看最外层。

排错第一步永远是把原始响应体完整打出来,别只 print 一句「请求失败」。厂商错误信息里通常已经写明了原因。

二、六类高频报错对照表

现象常见原因处理
401 UnauthorizedKey 没传 / 填错 / 已失效 / 环境变量没读到核对 Key 与请求头;确认进程读到了环境变量(D2)
403 ForbiddenKey 有效但无该模型权限 / 余额不足 / 地区限制查控制台模型权限与账单
429 Too Many Requests触发 RPM/TPM 限流指数退避重试 + 降并发,别立刻狂重打
超时 / 无响应网络抖动、长上下文生成慢、流式未读调大超时;流式改逐块读;加重试
context length exceeded历史消息 + 工具返回超模型上下文上限裁剪历史、摘要长结果、换长上下文模型(D5)
流式中止 / 半截 JSON连接被断、客户端提前关闭、未处理 done 信号按 SSE 逐块拼接,校验完整性后再解析

三、401 / 403:先查 Key,再查权限

401 最常见也最好修。按 D5 那篇的做法,Key 走环境变量、别硬编码。三个易漏点:请求头写错(应为 Authorization: Bearer <KEY>)、环境变量没被进程读到(改了 .env 但服务没重启)、把 base_url 和 Key 配到了不同厂商。

403 则是 Key 有效但「没资格」:模型未开通、余额用完、或该 Key 被限制了模型白名单。这类不用改代码,去控制台查权限和账单即可。

四、429:用指数退避,别用死循环

import time, random, requests

def call_with_retry(payload, max_retry=4):
    for attempt in range(max_retry):
        r = requests.post(API_URL, json=payload, headers=HEADERS, timeout=60)
        if r.status_code == 200:
            return r.json()
        if r.status_code == 429:                 # 只重试可恢复错误
            wait = (2 ** attempt) + random.random()   # 指数退避 + 抖动
            time.sleep(wait)
            continue
        raise RuntimeError(r.text)               # 其余错误直接抛,别盲目重试
    raise RuntimeError("重试次数用尽,请稍后再试")

要点:只对 429 和超时重试、等待时间指数增长并加随机抖动(避免多个请求同时醒来再次撞限流)、设最大次数。401/400 这类重试一万次也不会成功,直接抛错排查更快。

五、超时、超长与流式中止

  • 超时:长上下文或长输出本来就慢,把 timeout 从默认调到 60~120 秒;仍不稳就改流式。
  • 上下文超长:D14 的 Agent 循环里每轮都把历史全带上,几轮就爆了。只保留必要消息,长工具结果先摘要再回灌。
  • 流式中止:SSE 要逐块读并按 [DONE] 收尾,别在第一个 chunk 就尝试 json.loads 整个响应。

六、六步排错清单(按顺序走)

  1. 打原始响应:拿到状态码和 error.message。
  2. 核对 Key 与 base_url:确认两者属于同一厂商、Key 未失效。
  3. 确认权限与余额:403 类问题在这一步解决。
  4. 看限流:429 上指数退避,同时降并发。
  5. 量一下输入长度:超长就裁剪历史 / 摘要 / 换模型。
  6. 最后才怀疑网络:换超时、试 curl、确认代理与防火墙。

七、FAQ

Q:本地 Ollama(D14)也会 401 吗? 一般不会,本地接口通常不校验 Key。若你用了需要 api_key 的 SDK,随便填一个占位值即可;真报 401 先确认 base_url 没有误指到云端厂商。

Q:429 一直退避还是失败? 说明并发或总量超了套餐档位。除了重试,还要限制同时发出的请求数,或按 D5 的费用实测评估是否升档。

Q:怎么区分「超时」和「上下文超长」? 前者是没等到响应(客户端超时),后者是厂商明确返回错误体(400 且 message 提到 context length)。打原始响应就能分清。

小结

大模型 API 报错,六类里 401/403 查 Key 与权限、429 上指数退避、超长裁历史、超时调大 timeout 并改流式,基本覆盖九成场景。排错顺序固定为「打原始响应 → 核 Key → 查权限余额 → 看限流 → 量长度 → 最后怀疑网络」,别一上来就改业务代码。尤其记住:只对可恢复错误重试,且必须带上限。具体状态码、限流阈值与错误体字段以你所用厂商当天官方文档为准。

相关推荐

相关推荐

评论(0)
发表评论