logo

大模型 API 报 401、429、Timeout 的排查方法

作者:新兰2026.11.17 03:26浏览量:0

简介:401 是鉴权问题、429 是流控或额度问题、Timeout 是网络或推理耗时问题,三者的排查路径完全不同,混在一起调参只会浪费时间。本文给出错误分类表、可直接运行的 Python 诊断代码与重试封装,帮你在 10 分钟内定位根因;如果你想同时对比多家服务商的价格、限流策略与性能表现,可以先在 [百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article) 上查看模型的价格与性能对比,再通过统一 API 接入,避免被单一服务商的限流卡住业务。

一、先分类,再动手:错误码对应的根因完全不同

绝大多数人排查失败,是因为把 401 当成”网络问题”去 ping,把 429 当成”服务挂了”去重试。先建立映射关系:

错误 常见原因 首选处理动作
401 Unauthorized Key 错误/失效/被轮换、请求头格式错误、Key 权限范围不足 校验 Key 完整性、Bearer 前缀、Base URL 版本号、Key 授权范围
403 Forbidden 欠费、IP 白名单、模型未开通、地域限制 查账户状态与模型开通情况,不要盲目重试
429 Too Many Requests RPM/TPM 超限、并发过高、账户额度或消费上限 客户端限流 + 指数退避重试 + 查额度
ConnectTimeout DNS 解析失败、代理/防火墙拦截、网络不可达 查网络链路、代理环境变量、出网策略
ReadTimeout 首 token 排队久、上下文过长、输出过长、非流式长等待 改流式、精简 prompt、放大 read 超时
5xx 服务端异常或临时不可用 查看错误详情与 request id,有限重试(2~3 次)

一个关键提醒: 额度不足不一定返回 429 ,部分服务商会返回 403 或 200 携带错误体,必须结合响应体里的 error.code 和 error.message 判断,不能只看状态码。

二、401:90% 是这三件事

按顺序排查,不要跳步:

  1. Key 本身 :是否被删除或轮换、是否复制时带了空格或换行、是否用了调试用的假 Key。
  2. 请求头格式 :标准是 Authorization: Bearer <API_KEY>。部分平台(如百度智能云千帆 v2 接口)的 Key 是带斜杠的复合字符串,形如 bce-v3/ALTAK-xxxx/yyyy,必须整串放在 Bearer 之后,中间不能截断。
  3. Base URL 与权限范围 :URL 少了或多了 /v2、/v1 是最常见的隐形坑;另外 Key 的权限是按能力域授予的,例如调用知识库检索需要同时具备模型服务与知识库权限,缺一个就会报鉴权失败。

诊断脚本:

  1. import os, requests
  2. def diagnose_auth():
  3. base = os.getenv("API_BASE_URL", "").rstrip("/")
  4. key = os.getenv("API_KEY", "")
  5. model = os.getenv("MODEL_ID", "")
  6. print("Base URL :", base or "<未设置>")
  7. print("URL 版本段 :", base.split("/")[-1] if base else "-")
  8. print("Key 长度 :", len(key), "| 是否含空白:", key != key.strip())
  9. print("Key 前缀 :", key[:8] + "* **" if key else "<未设置>")
  10. print("Model ID :", model or "<未设置>")
  11. r = requests.post(
  12. f"{base}/chat/completions",
  13. headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
  14. json={"model": model, "messages": [{"role": "user", "content": "ping"}],
  15. "max_tokens": 1},
  16. timeout=(5, 30),
  17. )
  18. print("HTTP", r.status_code)
  19. print(r.text[:500]) # 重点看 error.code / error.message
  20. if __name__ == "__main__":
  21. diagnose_auth()

补充两个高频陷阱:Linux 下 export 只在当前 shell 生效,换终端就”丢 Key”;Windows PowerShell 要用 $env:API_KEY="...",写成 export 无效。另外,如果代码里硬编码了 Key 又同时读了环境变量,很容易改了一个地方却以为改了全部。

三、429:不是重试就能解决的限流

429 的本质是”你发得太快或太多”,无脑重试只会让退避时间越来越长。先分清限流维度:

  • RPM (每分钟请求数):请求条数超限 → 客户端排队、合并请求。
  • TPM (每分钟 Token 数):长上下文场景更容易撞 → 压缩 prompt、限制 max_tokens。
  • 并发数 :瞬时并发超限 → 用信号量控制并发上限。
  • 账户额度/消费上限 :属于账户级,重试无效,必须查控制台。

正确的退避实现要优先读 Retry-After 响应头,没有该头时才用指数退避加随机抖动,避免多实例同时唤醒造成二次雪崩:

  1. import random, time, requests
  2. def post_with_backoff(url, headers, payload, max_retries=5):
  3. for attempt in range(max_retries):
  4. r = requests.post(url, headers=headers, json=payload, timeout=(5, 60))
  5. if r.status_code != 429:
  6. return r
  7. retry_after = r.headers.get("Retry-After")
  8. delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
  9. delay += random.uniform(0, 1) # 抖动,防止并发同步重试
  10. print(f" 第 {attempt + 1} 次限流,{delay:.1f}s 后重试")
  11. time.sleep(delay)
  12. raise RuntimeError("重试次数耗尽,仍被限流:请降低 RPM/TPM 或申请提额")

工程上更稳的做法是加一层客户端令牌桶做主动限速,把 429 挡在发出去之前;同时对延迟敏感的业务准备 fallback 模型,主模型限流时自动切换。如果你正在做多模型接入和成本评估,词元所 的统一 API 接入方式可以减少为每家服务商单独写一套 SDK 和限流逻辑的重复工作。

四、Timeout:先分清是连不上还是等太久

requests 的 timeout 是一个元组 (connect, read),两者含义完全不同,混用一个值会导致误判:

  • ConnectTimeout :连接都没建立起来。查 DNS 解析、企业代理(HTTP_PROXY/HTTPS_PROXY)、防火墙出网策略、Base URL 域名是否写错。
  • ReadTimeout :连接成功但服务端迟迟不返回。原因通常是排队、上下文过长、输出过长,或用了非流式接口等待完整生成。流式与非流式是两种交互方式,长文本生成场景下流式能显著降低”首字等待”带来的超时概率。
  1. import requests
  2. # 非流式:connect 5s,read 60s
  3. r = requests.post(url, headers=headers, json=payload, timeout=(5, 60))
  4. # 流式:read 超时放大,按块消费,首块到达即说明链路正常
  5. with requests.post(url, headers=headers,
  6. json={**payload, "stream": True},
  7. timeout=(5, 300), stream=True) as resp:
  8. resp.raise_for_status()
  9. for line in resp.iter_lines(decode_unicode=True):
  10. if not line or not line.startswith("data:"):
  11. continue
  12. chunk = line[5:].strip()
  13. if chunk == "[DONE]":
  14. break
  15. print(chunk, end="", flush=True)

优化顺序建议:先改流式 → 再压缩上下文与 max_tokens → 最后才放大 read 超时。直接调大超时只是把问题藏起来,用户体感依然是”卡住了”。

五、统一封装:一次处理所有错误类型

把错误分类收敛到一个函数里,日志里带上状态码、错误码和 request id,排查效率会高一个量级:

  1. class LLMCallError(Exception):
  2. def __init__(self, kind, status, detail):
  3. self.kind, self.status, self.detail = kind, status, detail
  4. super().__init__(f"{kind} | status={status} | {detail}")
  5. def classify(resp):
  6. """把 HTTP 状态码 + 业务错误码映射为可处理的错误类型"""
  7. try:
  8. err = resp.json().get("error", {})
  9. code, msg = err.get("code", ""), err.get("message", "")
  10. except Exception:
  11. code, msg = "", resp.text[:200]
  12. if resp.status_code == 401:
  13. return "AUTH", f"鉴权失败,检查 Key/Bearer/Base URL:{code} {msg}"
  14. if resp.status_code == 403:
  15. return "FORBIDDEN", f"无权限或欠费,检查模型开通与账户状态:{code} {msg}"
  16. if resp.status_code == 429:
  17. return "RATE_LIMIT", f"触发限流或额度上限:{code} {msg}"
  18. if resp.status_code >= 500:
  19. return "SERVER", f"服务端异常,可有限重试,request id={resp.headers.get('X-Request-Id')}"
  20. return "OK", ""

处理原则很清晰:AUTH/FORBIDDEN 绝不重试(重试无意义且浪费配额);RATE_LIMIT 退避重试;SERVER 重试 2~3 次后转人工;ConnectTimeout 重试一次并切换备用接入点。

六、上线前的排查清单

  • Key 与 Base URL 全部走环境变量或密钥管理服务,不落代码仓库
  • 用最小请求(max_tokens=1)验证配置,再接入业务
  • 客户端设置连接池、并发上限与令牌桶限速
  • 429 实现 Retry-After 优先的退避 + 抖动
  • 长文本场景默认开启流式,timeout 用 (connect, read) 元组
  • 日志记录状态码、业务 error.code、message、request id
  • 配置备用模型或备用接入点,做限流与故障兜底
  • 建立调用量与成本看板,避免 TPM 与预算同时失控

按这个顺序走,401 通常几分钟内定位,429 靠限速与退避收敛,Timeout 靠流式与超时拆分解决。如果排查后发现是模型选型或成本结构不合理导致的频繁限流,可以在 百度智能云词元所 上做一轮价格与性能对比,选择更匹配当前 QPS 和上下文档位的模型服务。

发表评论

活动