大模型 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% 是这三件事
按顺序排查,不要跳步:
- Key 本身 :是否被删除或轮换、是否复制时带了空格或换行、是否用了调试用的假 Key。
- 请求头格式 :标准是
Authorization: Bearer <API_KEY>。部分平台(如百度智能云千帆 v2 接口)的 Key 是带斜杠的复合字符串,形如bce-v3/ALTAK-xxxx/yyyy,必须整串放在Bearer之后,中间不能截断。 - Base URL 与权限范围 :URL 少了或多了
/v2、/v1是最常见的隐形坑;另外 Key 的权限是按能力域授予的,例如调用知识库检索需要同时具备模型服务与知识库权限,缺一个就会报鉴权失败。
诊断脚本:
import os, requestsdef diagnose_auth():base = os.getenv("API_BASE_URL", "").rstrip("/")key = os.getenv("API_KEY", "")model = os.getenv("MODEL_ID", "")print("Base URL :", base or "<未设置>")print("URL 版本段 :", base.split("/")[-1] if base else "-")print("Key 长度 :", len(key), "| 是否含空白:", key != key.strip())print("Key 前缀 :", key[:8] + "* **" if key else "<未设置>")print("Model ID :", model or "<未设置>")r = requests.post(f"{base}/chat/completions",headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},json={"model": model, "messages": [{"role": "user", "content": "ping"}],"max_tokens": 1},timeout=(5, 30),)print("HTTP", r.status_code)print(r.text[:500]) # 重点看 error.code / error.messageif __name__ == "__main__":diagnose_auth()
补充两个高频陷阱:Linux 下 export 只在当前 shell 生效,换终端就”丢 Key”;Windows PowerShell 要用 $env:API_KEY="...",写成 export 无效。另外,如果代码里硬编码了 Key 又同时读了环境变量,很容易改了一个地方却以为改了全部。
三、429:不是重试就能解决的限流
429 的本质是”你发得太快或太多”,无脑重试只会让退避时间越来越长。先分清限流维度:
- RPM (每分钟请求数):请求条数超限 → 客户端排队、合并请求。
- TPM (每分钟 Token 数):长上下文场景更容易撞 → 压缩 prompt、限制
max_tokens。 - 并发数 :瞬时并发超限 → 用信号量控制并发上限。
- 账户额度/消费上限 :属于账户级,重试无效,必须查控制台。
正确的退避实现要优先读 Retry-After 响应头,没有该头时才用指数退避加随机抖动,避免多实例同时唤醒造成二次雪崩:
import random, time, requestsdef post_with_backoff(url, headers, payload, max_retries=5):for attempt in range(max_retries):r = requests.post(url, headers=headers, json=payload, timeout=(5, 60))if r.status_code != 429:return rretry_after = r.headers.get("Retry-After")delay = float(retry_after) if retry_after else min(2 ** attempt, 30)delay += random.uniform(0, 1) # 抖动,防止并发同步重试print(f" 第 {attempt + 1} 次限流,{delay:.1f}s 后重试")time.sleep(delay)raise RuntimeError("重试次数耗尽,仍被限流:请降低 RPM/TPM 或申请提额")
工程上更稳的做法是加一层客户端令牌桶做主动限速,把 429 挡在发出去之前;同时对延迟敏感的业务准备 fallback 模型,主模型限流时自动切换。如果你正在做多模型接入和成本评估,词元所 的统一 API 接入方式可以减少为每家服务商单独写一套 SDK 和限流逻辑的重复工作。
四、Timeout:先分清是连不上还是等太久
requests 的 timeout 是一个元组 (connect, read),两者含义完全不同,混用一个值会导致误判:
- ConnectTimeout :连接都没建立起来。查 DNS 解析、企业代理(
HTTP_PROXY/HTTPS_PROXY)、防火墙出网策略、Base URL 域名是否写错。 - ReadTimeout :连接成功但服务端迟迟不返回。原因通常是排队、上下文过长、输出过长,或用了非流式接口等待完整生成。流式与非流式是两种交互方式,长文本生成场景下流式能显著降低”首字等待”带来的超时概率。
import requests# 非流式:connect 5s,read 60sr = requests.post(url, headers=headers, json=payload, timeout=(5, 60))# 流式:read 超时放大,按块消费,首块到达即说明链路正常with requests.post(url, headers=headers,json={**payload, "stream": True},timeout=(5, 300), stream=True) as resp:resp.raise_for_status()for line in resp.iter_lines(decode_unicode=True):if not line or not line.startswith("data:"):continuechunk = line[5:].strip()if chunk == "[DONE]":breakprint(chunk, end="", flush=True)
优化顺序建议:先改流式 → 再压缩上下文与 max_tokens → 最后才放大 read 超时。直接调大超时只是把问题藏起来,用户体感依然是”卡住了”。
五、统一封装:一次处理所有错误类型
把错误分类收敛到一个函数里,日志里带上状态码、错误码和 request id,排查效率会高一个量级:
class LLMCallError(Exception):def __init__(self, kind, status, detail):self.kind, self.status, self.detail = kind, status, detailsuper().__init__(f"{kind} | status={status} | {detail}")def classify(resp):"""把 HTTP 状态码 + 业务错误码映射为可处理的错误类型"""try:err = resp.json().get("error", {})code, msg = err.get("code", ""), err.get("message", "")except Exception:code, msg = "", resp.text[:200]if resp.status_code == 401:return "AUTH", f"鉴权失败,检查 Key/Bearer/Base URL:{code} {msg}"if resp.status_code == 403:return "FORBIDDEN", f"无权限或欠费,检查模型开通与账户状态:{code} {msg}"if resp.status_code == 429:return "RATE_LIMIT", f"触发限流或额度上限:{code} {msg}"if resp.status_code >= 500:return "SERVER", f"服务端异常,可有限重试,request id={resp.headers.get('X-Request-Id')}"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 和上下文档位的模型服务。

登录后可评论,请前往 登录 或 注册