大模型 API 报 429、超时、余额不足：按错误定位的排查清单
区分 API 鉴权失败、限流、超时、余额不足与空正文。用最小请求定位问题，避免重复充值、无限重试和多层重试放大成本。
遇到 429 先看限流原因、降低并发；遇到超时先判断有没有收到响应；遇到余额不足先查当前地址对应的钱包。 这三类问题不能靠同一个“多试几次”解决。尤其超时不等于服务端没有处理，请求重发可能产生额外用量。
本文是一份逐项问答清单，以不墨 Router 的 Chat Completions 接入为例。模型 ID 和公开入口核验于 2026-10-24；通用排查建议不意味着每一种 HTTP 状态码都由 Router 在所有情形下固定返回。
先保留什么，才能避免越改越乱？
记录发生时间与时区、接口主机和路径、请求模型、HTTP 状态码、错误正文中的 type / code / message，以及服务端有返回时的请求 ID。再记录是否流式、当前并发和重试次数。分享记录前移除 Key、Cookie、用户隐私和完整敏感输入。
至少区分三种现象：收到非 2xx HTTP 响应；连接失败或等待超时；收到 200 但正文不符合预期。它们分别指向接口错误、网络或耗时、结果内容问题。只写“API 挂了”无法判断是哪一层。
如何排除客户端配置干扰？
先在调用程序所在的机器运行最小请求。下面命令适用于 macOS / Linux，Key 预先放在 BUMO_API_KEY 环境变量中，不在命令里写真实值：
curl --silent --show-error \
--connect-timeout 10 --max-time 120 \
--write-out '\nHTTP %{http_code}\n' \
https://router.bumo.cc/v1/chat/completions \
-H "Authorization: Bearer $BUMO_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"model":"deepseek/deepseek-flash","messages":[{"role":"user","content":"请回复一句简短问候。"}],"stream":false,"max_tokens":2048}'
有有效 Key 和余额时，这是一条可能计费的生成请求。它不带自动重试、不使用工具、不携带长历史，目的是让错误尽量容易解释。HTTP 000 不是服务端返回的状态码：它表示 curl 没拿到 HTTP 状态，需结合 curl 的报错与退出码看连接问题。
公开的 模型列表 可以先用 GET 查看，但列表能打开只证明目录可读，不证明 Key 有效、余额充足或具体模型的上游正常。
401：为什么换了 Key 还失败？
先检查三件事：Key 是否来自当前地址的平台，复制时是否带入空格或换行，应用是否确实读取了新环境变量。容器、服务器进程和本地终端的环境变量可能不同，改了终端并不会自动更新已启动的进程。
Router 的地址配 Router Key；原厂 Key 配原厂地址。不要为了排错把 Key 打到公共日志里。使用调试代理时也要确认它不会记录 Authorization 请求头。
404：模型不存在还是地址错了？
把完整请求路径打印出来，但不要打印鉴权信息。HTTP 请求应发往 /v1/chat/completions；SDK 的 Base URL 通常只到 /v1。把完整路径填进 SDK 的 base_url，可能让 SDK 再拼接一次，形成错误路径。
模型 ID 从列表复制，不从文章标题猜。例如本文使用 deepseek/deepseek-flash，不是自行拼接的版本别名。收到 HTML 错误页时，更应先查域名、路径和反向代理，而不是改模型参数。
429：充值能解决吗？
不一定。先读错误正文：请求数、token 速率、并发、账号配额、上游容量属于不同约束。降低并发适合速率类问题；若正文明确指向余额或配额，就应处理对应账号限制。不要把所有 429 都翻译成“没钱了”。
对于允许重试的临时限流，在应用里设置最大尝试次数和总等待期限；有 Retry-After 时按服务端提示等待，等待时间超出任务期限则停止。没有提示时可以用带随机抖动的指数退避。例如依次等待约 1、2、4 秒，是策略示例，不是 Router 承诺的限流窗口。
检查 SDK、任务队列、工作流节点三层是否都在重试。如果每层都允许总共 3 次尝试，最坏可能放大到 27 次下游调用。先确定由哪一层负责，其他层避免重复包装。
余额不足：为什么刚充过还报错？
确认登录的是发出该 Key 的账号，查看充值订单是否成功到账，再检查调用域名所属环境。Router、原厂平台以及其他产品的钱包不可凭名称相似就视为互通。
当前 Router 代码中的余额检查使用 402 与 billing_error / Insufficient balance；这只是排查线索，实际仍以你收到的响应为准。不要改模型名、延长超时来处理明确的余额错误，也不要只因一个不明错误反复充值。
超时：该加长等待，还是重发？
先分连接建立前与响应等待中。DNS、TLS、出口代理问题，延长生成时间无助于根因。已经连接但迟迟没结果时，再检查输入长度、模型推理耗时与网关或客户端的超时设置。
生产环境要让内部调用超时与外层业务期限相协调，并保留清晰的失败状态。流式接口还要区分首个事件、首段最终文本和完整结束：思考或心跳事件到达，不代表最终答案已经产生。
如果流式中途断开，不要把第二次请求的全文接到第一次的残片后；也不要假定第一次一定未计费。先记录任务状态，再根据业务决定重试或让用户重新发起。
200 但没有答案，是否应该切模型？
先看 choices、finish_reason、message.content 和 usage。因输出上限而停止时，推理可能占用了预算；工具调用响应也可能没有普通最终文本。你的解析代码如果只读取一种字段，就可能把合法响应当成空结果。
把原始响应在受控环境中留样，确认结构后再修解析。确需切模型时，先用相同短输入对照，避免同时修改五个参数，最后无法判断哪个改动起作用。
排查什么时候算结束？
最小请求成功只是第一关。再用原业务的一条脱敏输入复测，确认结果完整、重试次数合理，并核对用量记录。本文已检查最小请求的 JSON、URL 与模型 ID；未人为制造线上限流、余额不足或超时，也没有声称验证所有错误的实时返回形式。
打开 Router 查看模型、Key 与账户信息。提交支持请求时附上脱敏的时间、状态码和错误正文，比只发一张“失败”截图更容易定位。
