酒馆报错弹出一个数字,你心想"这又是啥",然后开始 Google。

下面这张速查是我自己用过的,按概率排序。看完它,90% 的报错你自己能搞定。

记不住没关系——这页收藏起来,下次报错回来翻就行。

401 - 鉴权失败

意思:服务器不认识你。Key 错了,或者 Key 失效了。

最常见的真实原因:

  1. Key 复制时少/多了字符(90% 的 401 都是这个)
  2. Key 已经在平台被撤销(去后台看)
  3. 你填的端点和 Key 不匹配(把中转 A 的 Key 填到了中转 B 的端点)

怎么处理:

  • 第一步重新复制粘贴 Key,先排除手抖
  • 第二步去 API 平台看 Key 状态
  • 第三步换一把 Key 测

403 - 禁止访问

意思:服务器认识你,但不让你干这件事。

真实原因:

  1. 你的账号被风控/封禁
  2. 这个模型你没权限调用(账号等级不够)
  3. 内容触发了平台的强制审查
  4. 你的 IP 被该平台拉黑(很罕见,通常是公司网或机房 IP)

怎么处理:

  • 看错误信息里的细节,有时候会告诉你"模型未授权"
  • 去 API 平台后台看是不是收到了违规通知
  • 换 IP 或换模型试试

404 - 找不到

意思:你访问的地址不存在,或者你点的模型不存在。

真实原因:

  1. 端点 URL 写错了(漏了 /v1,或者多了 /chat/completions)
  2. 模型名错了(Claude Sonnet 而不是 claude-sonnet-{版本号}-{日期})
  3. 中转商不支持你选的模型

怎么处理:

  • 100% 是 URL 或模型名问题
  • 去平台官网的"模型列表"页,直接复制完整 slug
  • 端点别带 /chat/completions

429 - 太频繁了

意思:你这分钟内请求太多了,被限速了。

触发场景:

  1. 你猛点重试按钮(典型新人)
  2. 多人共享同一个 Key(中转商分给多用户)
  3. 平台对免费用户设了硬限额

怎么处理:

  • 等 30-60 秒,然后慢点试
  • 别一直重试,越重试越严重
  • 升级账号等级(如果有这个选项)
  • 换中转商(便宜的中转往往限速更狠)

500 - 服务器内部错误

这个最常见,单独一篇详细排查,见 《Valid 但 500 完整指南》。

意思:对方挂了。

这个最复杂。它不一定是服务器问题,可能是你的请求让对方处理不了。

真实原因(按概率):

  1. 模型名错(70%)
  2. 参数兼容性问题(15%)——比如 Claude 不接受 Frequency Penalty
  3. 余额为 0 但 Key 还有效(10%)
  4. 上游真的炸了(5%)

详细排查:Valid 但 500 完整指南

502 - 网关错误

意思:中间那层挂了。

跟 500 的区别:500 通常是 AI 服务本身的问题,502 是 AI 服务前面的代理/网关挂了。对你来说差不多——都是上游挂了。

怎么办:

  • 等 5 分钟再试
  • 切到备用渠道
  • 群里问问别人有没有同样问题(都炸了说明大事故,等就行)

503 - 服务不可用

意思:服务在,但暂时不能给你用(过载或维护)。

通常:

  • 等 5-10 分钟自动恢复
  • 高峰期(对应美东工作时间的晚上,北京时间上午)出现概率最高

504 - 网关超时

意思:中间那层等你的请求等太久,放弃了。

触发:

  • 你的请求太长(上下文几十万 token)
  • 上游响应太慢
  • 网络有问题

怎么办:

  • 缩短上下文(总结、隐藏旧楼)
  • 关闭流式输出
  • 换网络/换节点

ECONNRESET / socket hang up

意思:连接被对方掐断了。

触发:

  • 流式输出过程中代理切断
  • 你的网络抖动
  • 上游临时故障

怎么办:

  • 关闭 Stream(80% 解决)
  • 换网络
  • 重新发一次

一句总结

错误码不是"代码出 bug 了",是"服务器在用一个数字告诉你它的心情"。

  • 4xx 都是你的事(填错了、Key 没了、内容违规)
  • 5xx 都是它的事(它挂了、它累了、它崩了)

记住这条原则,大部分时候你不用 Google,自己就能定位。

相关阅读