中转 API 401、403、429、无可用渠道：真实报错排查手册

先按请求阶段分类，不要只背错误码

中转 API 的错误可能来自客户端、网关、账户、模型路由或上游厂商。同一个 429，既可能是每分钟请求过多，也可能是余额耗尽；同一个 404，既可能是路径错误，也可能是模型未部署。正确排查方法是确认请求走到了哪一层，再决定改 Key、改协议还是联系中转站。

第一层：连接与地址

如果表现为 DNS 解析失败、TLS 证书错误、连接超时或 HTTP 000，请求尚未进入鉴权。先用 curl -v 检查最终域名、证书和连接时间，确认 Base URL 没有隐藏空格、重复 /v1 或错误端口。

能打开中转后台网页，不代表 API 子域名可用；反过来，API 返回 404 也不代表服务器离线。把“网络失败”和“HTTP 错误”分开记录。

401：鉴权没有通过

真实案例中最常见的四个原因是：Key 复制不完整、Key 已被撤销、鉴权头用错、请求被发到错误的站点。Anthropic 原生接口通常使用 x-api-key，OpenAI 兼容接口通常使用 Bearer。

最小化排查：删除 SDK 和业务代码，只保留一个固定请求；打印最终 URL 和请求头名称，但不要打印完整 Key；分别按服务商明确支持的协议测试。若更换已知有效 Key 后成功，原 Key 有问题；若所有 Key 都失败，更可能是地址或协议配置。

403：Key 存在，但当前请求不被允许

403 常见于模型权限、用户分组、来源 IP、地区限制或风控。中转后台显示有余额，也可能没有目标模型权限。检查账户套餐、模型分组和 IP 白名单；如果错误体出现 policy、region、permission 等字样，应保留原文给服务商，而不是盲目重试。

404：路径和模型要分开查

路径不存在时，换模型通常没有用；模型不存在时，修改 URL 也没有用。观察错误体是否包含 model、deployment、route 等字段，并尝试读取服务商提供的模型列表。不要假设网页展示名就是 API model ID。

特别注意 SDK 自动拼接路径：Base URL 配成 https://example.com/v1 后，SDK 可能再追加 /v1/messages。抓取最终请求 URL 可以立即发现这类问题。

429：限流、余额和上游拥堵

429 至少分三类：短周期速率限制、账户额度不足、上游渠道无容量。连续快速重试只会加重第一类问题。先读取 retry-after 和错误码，再看中转余额和并发限制。

如果低频最小请求仍持续 429，且错误提示包含 quota、balance 或 credit，应处理额度；如果只在高峰出现并带有 channel、upstream、overloaded，则更可能是中转路由池问题。记录具体时间和模型，有助于判断是否集中在某个上游。

“无可用渠道”是中转层错误

这通常表示网关认识你的 Key 和模型，但当前没有符合分组、价格或健康状态的上游。用户侧能做的是确认模型名和账户分组，然后等待或换模型。反复更换请求正文一般无效。

如果商家长期把“无可用渠道”包装成用户参数错误，应要求其提供支持模型和路由状态说明。

5xx：先判断是否可重试

502/503 常见于网关连不上上游或上游过载；500 也可能是中转解析某个字段时崩溃。用同一请求间隔 10、30、60 秒重试三次，并尝试一个最小非流式请求。最小请求成功而复杂请求失败，通常是字段兼容问题；所有请求都失败，则更像服务端故障。

对写操作或有成本的长请求，不要无脑自动重试。每次重试都可能被上游计费，即便客户端最终只看到错误。

推荐记录模板

有了这张表，就能快速判断问题是单 Key、单模型、单协议还是整个站点故障。

用检测报告缩短定位时间

CheckToken 会先验证地址和 Key 格式，再进行协议探测和主请求。主请求失败时保留阶段与 HTTP 状态；只有部分能力探针失败时，其他项目仍会完成，并把错误单独标出。

检测报告不是替代服务商日志，而是把问题缩小到可沟通的范围。提交工单时附上时间、模型、协议、request ID 和脱敏错误，通常比一句“用不了”更容易得到有效处理。