401、429、502 API 错误排查

排查 API 错误时，先记录 状态码、响应正文、请求 ID、模型名和发生时间。只看“调用失败”四个字，很难判断问题位于客户端、网关还是上游模型。

开始前检查

用最小请求复现，暂时关闭流式输出、工具调用和长上下文。确认短请求也失败后，再进入状态码排查。

curl https://www.aifast.club/v1/models \
  -H "Authorization: Bearer $AIFAST_API_KEY" \
  -i

配置步骤

401 Unauthorized

401 表示身份验证没有通过。依次检查：

1. Key 是否完整、有效且属于当前账号。
2. 请求头是否为 Authorization: Bearer ...。
3. Key 前后是否有空格、换行或多余引号。
4. 客户端是否自动添加 Bearer，导致重复。
5. 环境变量是否在当前进程中生效。

401 通常不应该自动重试。认证信息不变时，重试只会重复失败。

429 Too Many Requests

429 可能表示：

• 请求频率超过限制。
• 并发数过高。
• 账号余额或配额不足。
• 特定模型处于繁忙状态。

处理顺序：降低并发、增加指数退避、检查余额和用量，再确认是否只有单个模型受影响。

第 1 次等待 1 秒
第 2 次等待 2 秒
第 3 次等待 4 秒
达到上限后停止，不无限重试

502 Bad Gateway

502 通常发生在网关无法从上游获得有效响应。常见原因：

• 上游模型临时异常。
• 长任务超过代理超时。
• 流式连接中断。
• 请求体过大或上下文过长。
• 网关与上游协议不兼容。

先换成短输入、关闭流式输出并保持同一模型测试。短请求成功而长请求失败，优先检查超时和上下文，而不是 Key。

504 或客户端 timeout

区分三类超时：

代理任务在执行工具时可能暂时没有文本输出，读取超时不能设置得和普通聊天一样短。

常见问题

是否应该遇到任何错误都重试

不应该。建议：

• 401、400、模型不存在：修正配置，不重试。
• 429、部分 5xx、短暂网络中断：有限重试。
• 有副作用的工具调用：先保证幂等，再考虑重试。

需要向客服提供什么

提供发生时间、模型 ID、状态码、请求 ID 和脱敏后的错误正文。不要发送完整 API Key，也不要把用户隐私数据直接贴入工单。

下一步

建立统一错误日志，把请求 ID、模型、耗时、输入输出 tokens、重试次数和最终状态放在同一条记录中。这样才能判断某个错误是偶发还是持续问题。