LLM API 报错排查指南：401、429、超时一次讲清

接入大模型 API 的第一天，你大概率不会先遇到成功响应，而是先遇到一段英文报错：401、429、timeout。这三个错误占了新手排障时间的 90%，但绝大多数并不需要联系服务商——按本文的方法，三分钟内自己就能定位。

一、先看速查表：报错代码对号入座

二、401 鉴权失败：三步定位法

401 是最常见也最容易误判的错误。很多人一看"Invalid API Key"就去反复生成新 Key，其实问题往往不在 Key 本身。按下面三步走：

第一步：用 curl 绕过你的代码直测。这一步能立刻把"Key 有问题"和"代码有问题"切开：

curl https://yingsuan.top/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的Key" \
  -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "hi"}]}'

curl 返回正常回复，说明 Key 和网络都没问题，问题一定在你的代码里。常见代码侧坑有三个：

• 环境变量没生效：改了 .env 但进程没重启，代码读到的还是空值或旧值；
• Bearer 拼写或空格问题：正确格式是 Authorization: Bearer sk-xxx，注意 B 与earer 之间一个空格，Key 前后不能有换行；
• base_url 写错：这是重灾区。网上抄来的示例里写着各种根本不存在的域名，DNS 都解析不了。先用 ping 或浏览器确认域名真实可达。

三、429 限流：不是故障，是规则

429 表示你触发了速率限制（RPM = 每分钟请求数，TPM = 每分钟 token 数）。免费额度通常限 5 RPM 左右，并发跑批时很容易撞上。正确姿势是指数退避重试，而不是疯狂刷新：

import time, requests

def call_with_backoff(payload, headers, max_retry=5):
    for i in range(max_retry):
        r = requests.post(
            "https://yingsuan.top/v1/chat/completions",
            json=payload, headers=headers, timeout=60)
        if r.status_code == 429:
            wait = 2 ** i          # 1, 2, 4, 8, 16 秒
            time.sleep(wait)
            continue
        return r
    raise RuntimeError("多次重试后仍被限流，请降低并发或申请提额")

三个实用建议：

• 批量任务加间隔：5 RPM 意味着每分钟最多 5 次请求，循环里加 time.sleep(13) 是简单粗暴但有效的方案；
• 读响应体里的提示：规范的服务商会在 429 响应里告诉你还剩多少额度、何时恢复；
• 需要高并发就升级：限流保护的是所有用户的公平性，生产负载应该走付费套餐拿独立配额。

四、超时与 5xx：分层定位

超时最忌讳"哪里慢就无限等"。正确做法是先给足合理的 timeout，再分层排查。用 curl 的计时参数可以看清每一段耗时：

curl -w "DNS解析: %{time_namelookup}s\nTCP连接: %{time_connect}s\n服务响应: %{time_starttransfer}s\n总耗时: %{time_total}s\n" \
  -o /dev/null -s https://yingsuan.top/v1/models \
  -H "Authorization: Bearer sk-你的Key"

• DNS 解析慢：本地网络或 DNS 配置问题，换 223.5.5.5 试试；
• TCP 连接慢：跨境链路或本地防火墙问题，国内服务器直连通常毫秒级；
• 服务响应慢：可能是长推理（reasoner 类模型生成本来就要几十秒），把客户端 timeout 调到 120 秒以上，或改用流式输出（stream: true）先拿到首 token。

5xx 是服务端问题，重试策略与 429 类似但等待时间可以更长（30 秒起步）。如果同一模型连续失败超过 10 分钟，换个模型先跑通业务，再向服务商反馈——这也是聚合网关的价值：一个模型故障，一键切到备选模型。

五、通用排查工作流：四步走

六、常见问题 FAQ