一句话结论
401 改 Key、429 等一会、503 换上游、524 缩短任务或换模型。
适用场景
- 调用接口时看到一串数字错误
- Agent 跑一半突然报错
- 想区分哪些是自己问题、哪些是平台问题
常见现象
- 401 Unauthorized
- 429 Too Many Requests
- 503 Service Unavailable
- 524 A timeout occurred
原因解释
- 401：Key 错、过期或被禁
- 429：超过 RPM/TPM 限制
- 503：上游模型或中转站短暂挂掉
- 524：单次请求处理超时（常见 100 秒以上）
解决步骤
- 401：核对 Key、确认是否粘错、是否被作废
- 429：暂停几秒再重试，必要时降并发
- 503：换一个模型或中转站，等几分钟
- 524：把长任务切成小段，或者换更快模型
可复制命令
curl -i $BASE_URL/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"
仍然不行怎么办
- 持续 503 / 524 就换中转站或模型
- 持续 401 就到平台重新生成 Key
小白先准备什么
- 确认自己用的是哪个平台的 Key（OpenAI / 1A1API / Claude）
- 准备好能跑 curl 的终端（Mac 自带，Windows 用 Git Bash 或 PowerShell）
- 把报错的完整响应保存下来（不只是状态码，还有 body 里的 message）
- 确认账户余额和 Key 状态（是否被禁用）
验收标准
- 能根据状态码判断问题出在自己还是平台
- 401 → 能在 5 分钟内定位是 Key 错误还是过期
- 429 → 知道等多久或降多少并发
- 503 → 知道该换模型还是等恢复
- 524 → 知道该缩短任务还是换模型
可复制排查提示词
遇到 API 报错时，把下面这段和错误信息一起发给 AI：
我调用模型 API 时遇到报错：
状态码：<401/429/503/524/其他>
完整错误信息：
```
<粘贴响应 body>
```
我的配置：
- 平台：<OpenAI/1A1API/其他>
- 模型：<gpt-4o/claude-sonnet-4-6/其他>
- 并发数：<同时跑几个请求>
请帮我：
1. 判断问题出在我这边还是平台那边
2. 给出具体修复步骤
3. 如果是平台问题，告诉我怎么临时绕过
常见误区
- 误区：429 就是被封了 → 只是限速，等一会或降并发就好
- 误区：503 是自己的问题 → 503 是上游挂了，不是你的配置错
- 误区：所有错误都重试就行 → 401 重试没用，必须修 Key；429 要等，不能立刻重试
- 误区：524 是网络问题 → 524 是请求处理超时，通常是任务太长或模型太慢
还卡着？
可以把截图、日志、需求单或当前页面链接发到 zhemuy@gmail.com。