大模型 API 常见报错怎么排查：401、404、429、500 与上下文超限
调用大模型 API 时出现报错，不要慌。先看 HTTP 状态码，再看返回的文字说明，大多数问题几分钟就能定位。
按状态码快速定位#
| 状态码 | 常见原因 | 怎么办 |
|---|---|---|
| 400 | 请求格式不对；模型不支持某个参数；上下文超过上限 | 检查请求体；减少历史内容或新开会话 |
| 401 | 令牌无效、写错、被禁用，或接口地址填错 | 重新复制令牌；确认没有多余空格和换行 |
| 402 / 403 | 余额或额度不足；令牌没有该模型或分组的权限 | 充值或换有权限的分组 |
| 404 | Base URL 多写或少写了 /v1；模型名不存在 | 对照文档检查地址和模型名 |
| 408 / 504 / 524 | 请求超时，上游生成太慢 | 缩短输入、改用更快的模型，或稍后重试 |
| 413 | 请求体太大（例如图片或文件过大） | 压缩或拆分内容 |
| 429 | 请求太频繁、并发太高，或上游额度/限流 | 降低并发，等待后重试 |
| 500 / 502 / 503 | 上游临时故障、无可用渠道、流提前中断 | 稍后重试；持续出现则换模型或反馈 |
几个高频场景#
1. 401：明明复制了令牌#
- 令牌前后多了空格或换行。
- 环境变量没生效：改完后要重启终端和客户端，Windows 注意退出右下角托盘里的客户端。
- 用错了接口地址，比如把别的站点的地址配上了这里的令牌。
2. 404：路径或模型不对#
Claude 系客户端的 Base URL 一般不带 /v1，OpenAI 系客户端（Codex、各类 SDK）要带 /v1。另外，模型名必须是令牌所在分组里存在的，大小写和连字符要完全一致。
3. 429：限流#
可能是你自己并发过高，也可能是上游账号暂时达到额度或限流。处理方式：
- 降低并发，给请求加间隔。
- 用带退避的重试（见下面的代码）。
- 如果长时间一直 429，换一个同类模型，或在群里反馈。
4. 上下文超限#
典型提示包含 maximum context length、prompt is too long 或 context_length_exceeded。说明这次发出的内容（历史加新问题）已经超过模型的上下文窗口。办法：
- 新开会话，只带必要的信息。
- 先压缩历史再继续。
- 避免一次性贴入巨大的日志。
原理见 上下文窗口、输出上限与缓存计费。
5. 502 / 503：上游问题#
这类错误多数是上游暂时不可用，重试通常就好。流式输出中途断开，表现为「回答说到一半就停了」，同样可以重试。
带退避的重试代码#
对 429 和 5xx 做指数退避重试，能解决大部分临时性故障：
import random
import time
import requests
URL = "https://cdn.5202828.xyz/v1/chat/completions"
HEADERS = {"Authorization": "Bearer sk-你的令牌", "Content-Type": "application/json"}
def call(payload, retries=4):
resp = None
for i in range(retries):
resp = requests.post(URL, headers=HEADERS, json=payload, timeout=120)
if resp.status_code in (429, 500, 502, 503, 504):
time.sleep(min(2 ** i, 20) + random.random())
continue
return resp
return resp注意：401、403、404 这类错误重试没有意义，要先修正配置。
在鹊桥遇到报错怎么办#
鹊桥返回的常见报错现在带有中文原因和处理建议，先按提示操作。如果还是不行，请加鹊桥 QQ 群 538642822 找群主，发这三样：
- 报错截图
- 发生时间
- 令牌名（或分组）
这样可以最快定位。配置方面的问题，也可以先看 CC Switch 是什么？一键配置 Claude Code、Codex 与 DeepSeek Harness。