返回博客
AI APIAPI 错误401404429502故障排查

AI API 返回 401、404、429、500、502、503，应该怎么处理？

用一套可执行的排查顺序定位 AI API 的认证、地址、限流、额度和上游故障，并判断哪些错误适合重试。

AI API 返回 401、404、429、500、502、503，应该怎么处理？

AI API 常见的 401、404、429 与 5xx 错误

调用 AI API 时，状态码不是一句模糊的“请求失败”，而是在告诉你问题最可能发生在哪一层：

  • 401：认证信息缺失或无效；
  • 404：接口路径、资源或模型地址不存在；
  • 429：请求过快，或者额度不足；
  • 500：网关或上游发生内部错误；
  • 502：网关没有从上游获得有效响应；
  • 503：服务暂时不可用或过载。

真正高效的排错方式不是反复更换模型、重启程序和无限重试，而是先保存完整响应，再按状态码检查对应层级。本文结合 Nbility API 错误文档、OpenAI 和 Anthropic 的官方错误说明，整理一套适用于聊天、编程 Agent、图片及视频接口的排查流程。

先保存完整错误上下文

不要只记录一句 API Error。至少保存以下信息：

HTTP 状态码
错误响应中的 message、type、code
请求时间与时区
请求 URL（不含密钥）
使用的模型名
客户端或 SDK 版本
脱敏后的请求 ID / trace ID
是否为流式请求
是否重试过以及重试次数

Nbility 的标准错误响应格式为：

{
  "error": {
    "message": "A human-readable error description",
    "type": "error_type",
    "code": "error_code"
  }
}

状态码相同，code 可能不同。例如 429 既可能是 rate_limit_exceeded，也可能是 insufficient_quota。两者的解决方法完全不同。

日志中不得记录完整 Authorization、API Key、Cookie、用户对话或未脱敏文件内容。需要提交工单时，通常提供时间、错误码、请求 ID 和密钥的少量前后缀就够了。

一张表快速判断

状态码最常见原因先检查什么是否适合自动重试
400JSON 或参数错误请求体、字段名、类型否
401Key 缺失或无效认证头、环境变量、Token 状态否
403权限不足Token 分组、模型权限、IP/地区策略否
404URL、路径或资源不存在Base URL、/v1、接口协议否
429限流或额度不足错误 code、余额、并发视原因而定
500服务内部或上游错误响应体、请求 ID、服务状态可以，有限次数
502上游返回无效响应网关与上游状态可以，有限次数
503服务不可用或过载服务状态、容量、稍后重试可以，有限次数

核心原则是：先判断错误能否通过重试自行恢复，再决定是否重试。 配置错误和权限错误不会因为多请求几次而消失。

401 Unauthorized：先查 Key，不要先重试

401 认证错误与 404 地址错误的检查方向

Nbility 将 401 定义为 API Key 缺失或无效，常见错误码是 invalid_api_key。依次检查：

[ ] Authorization 头是否存在
[ ] 是否使用正确的 Bearer 格式
[ ] Key 前后是否带空格、引号或换行
[ ] 环境变量是否被当前进程加载
[ ] 是否误用了网页登录 Token 或其他平台的 Key
[ ] Token 是否已撤销、过期或被禁用
[ ] 请求是否发到了创建该 Key 的正确服务

OpenAI 兼容请求通常使用：

Authorization: Bearer YOUR_API_KEY

用 curl 做最小测试时，可让 Shell 从环境变量读取 Key，避免它进入命令历史：

export NBILITY_API_KEY="YOUR_API_KEY"

curl https://api.nbility.ai/v1/models \
  -H "Authorization: Bearer $NBILITY_API_KEY"

不要用以下方式排错：

echo "$NBILITY_API_KEY"

它会把完整密钥输出到终端、录屏或日志。只检查变量是否存在即可：

if [ -n "$NBILITY_API_KEY" ]; then
  echo "API key is set"
else
  echo "API key is missing"
fi

401 和 403 有什么区别？

通常可以这样理解：

  • 401：服务无法确认你是谁，或凭据无效；
  • 403：服务已经识别凭据，但不允许当前操作。

如果 Key 有效，但 Token 分组不支持目标模型、IP 不在允许列表或账号受策略限制，更可能出现 403。这时反复创建相同请求没有意义，应检查权限。

404 Not Found：检查 Base URL、/v1 和协议

404 表示资源或接口不存在。AI API 场景中，最常见的不是服务器“消失”，而是地址拼错：

https://api.example.com/v1/v1/chat/completions
https://api.example.com/chat/completions
https://api.example.com/v1/responses
https://api.example.com/v1/messages

这些路径分别属于不同客户端和协议。排查时把最终请求 URL 拆成三部分：

服务域名 + API 版本 + Endpoint

以 Nbility 为例：

OpenAI Chat Completions: https://api.nbility.ai/v1/chat/completions
OpenAI Responses:        https://api.nbility.ai/v1/responses
Claude Messages:         https://api.nbility.ai/v1/messages

但客户端的 Base URL 填法不一定等于完整请求地址：

  • OpenAI 兼容 SDK 通常填写 https://api.nbility.ai/v1；
  • Claude Code 的 ANTHROPIC_BASE_URL 使用 https://api.nbility.ai，客户端自行拼接 /v1/messages。

因此，看到 404 时应查看客户端最终请求的 URL，而不是只看配置界面。常见问题包括：

  • Base URL 和客户端同时追加 /v1；
  • 把完整 Endpoint 当成 Base URL；
  • 用 Responses API 客户端请求只支持 Chat Completions 的地址；
  • 路径拼写错误；
  • 请求一个已经删除的任务或文件资源；
  • 反向代理没有转发该路由。

429：先区分限流和额度不足

429 限流后的指数退避重试

429 Too Many Requests 至少有两种常见含义。

请求过快：rate_limit_exceeded

处理方式：

  1. 降低并发；
  2. 限制每秒请求数；
  3. 优先读取服务返回的 Retry-After；
  4. 使用指数退避和随机抖动；
  5. 设置最大重试次数；
  6. 对批处理使用队列。

一个简化的重试等待序列可以是：

1 秒 → 2 秒 → 4 秒 → 8 秒

实际生产中应加入 jitter，避免所有客户端同时再次请求：

import random
import time

for attempt in range(4):
    delay = min(8, 2**attempt) + random.uniform(0, 0.5)
    time.sleep(delay)
    # retry request here; stop immediately after success

额度不足：insufficient_quota

指数退避解决不了余额耗尽。应检查：

  • 账户余额；
  • Token 的额度或有效期；
  • 项目/团队预算；
  • 模型分组是否允许调用；
  • 是否触发每日或每月消费上限。

因此不要只根据 HTTP 429 决定重试，必须同时读取错误体中的 code 和 message。

500、502、503：服务器错误不等于无限重试

500、502、503 的含义与重试流程

500 Internal Server Error

代表网关或上游在处理请求时发生未预期错误。Nbility 的 upstream_error 和 unmarshal_response_body_failed 也可能表现为 500。

先检查请求体是否过大、流式格式是否异常，以及错误是否稳定复现。如果只有某一模型、某一参数组合持续触发，应保存最小化请求并提交工单。

502 Bad Gateway

表示网关作为中间层，没有从上游获得有效响应。常见原因：

  • 上游连接被关闭；
  • 上游返回了网关无法解析的内容；
  • TLS、代理或 DNS 短暂失败；
  • 流式响应中途断开；
  • 上游超时后被代理转换为 502。

503 Service Unavailable

通常表示服务暂时不可用、维护或过载。与永久配置错误相比，503 更适合在短暂等待后重试。

推荐的 5xx 重试策略

仅对幂等或可安全重复的操作自动重试。建议：

最多重试 2–3 次
使用指数退避和 jitter
设置每次请求的超时
记录每次失败的请求 ID
达到上限后立即失败并告警
避免多个系统层同时重试

聊天请求重复一次通常只是重复生成，但图片、视频、充值、创建任务等接口可能产生重复任务或重复费用。重试前要确认接口是否幂等，或使用幂等键/任务 ID 做去重。

502 和 504 为什么有时会由代理返回？

你的调用链可能是：

客户端 → CDN → 反向代理 → API 网关 → 上游模型

每一层都有自己的连接超时和响应超时。即使模型最终完成生成，前面的代理也可能先返回 502 或 504。排查时比较：

  • 客户端超时；
  • CDN 或反向代理超时；
  • 网关上游超时；
  • 模型最大处理时间；
  • 流式连接的 idle timeout。

不要简单地把所有 5xx 都归因于模型供应商。

一套从客户端到上游的排查顺序

第 1 步：用最小请求复现

去掉工具调用、图片、长上下文和复杂参数，只保留最简单的一条消息。若最小请求成功，再逐项加回参数。

第 2 步：确认最终 URL 与协议

记录实际请求 URL、HTTP 方法和内容类型。确认客户端使用 Chat Completions、Responses 还是 Claude Messages。

第 3 步：验证认证但不泄露密钥

只确认认证头存在、格式正确、Token 有效，不在日志中输出完整值。

第 4 步：核对模型权限

模型名必须与当前 Token 可用列表完全一致。model not found 有时返回 400 或 404，不能只依赖状态码。

第 5 步：判断是否可重试

400 / 401 / 403 / 404 → 修改请求或配置，不自动重试
429 rate limit       → 按 Retry-After 或退避重试
429 quota            → 补充额度或调整限制
500 / 502 / 503      → 有限重试，持续失败则记录并上报

第 6 步：带着证据提交工单

向支持团队提供：

发生时间与时区
状态码、error.code、error.message
脱敏请求 URL
模型名
是否流式
请求 ID / trace ID
最小复现步骤
已尝试的排查动作

这比“API 用不了，麻烦看看”更容易定位。

生产环境应该怎么设计

一个稳定的 AI API 客户端至少应该具备：

  • 连接和读取超时；
  • 仅针对可恢复错误的有限重试；
  • 指数退避与随机抖动；
  • 并发限制和请求队列；
  • 结构化错误日志；
  • 请求 ID 透传；
  • 密钥脱敏；
  • 按状态码和模型的监控；
  • 5xx 与延迟异常告警；
  • 图片、视频和其他任务的幂等或去重机制。

最终目标不是“让所有请求永远成功”，而是让错误能够被正确分类、有限恢复，并在无法恢复时留下足够证据。

如果你正在使用 Nbility，可以查看 API 错误码文档和快速开始。持续出现的上游错误可通过工单页面提交，注意对密钥和业务数据进行脱敏。

参考资料

相关文章

用 Nbility 跑通你的 Agent 工作流

获取 API Key，统一接入 OpenAI 兼容模型和开发工具。

管理 API Key