AI API 网关常见 401、403、404、429 与 5xx 错误排查

调用 AI API 时401、403、404、429、502和504经常被混在一起处理。实际排查中这些状态码分别对应鉴权、权限、路由、限流和上游链路等不同层级。如果一看到错误就更换模型、重复生成密钥或反复重试往往会掩盖真正原因。本文给出一套从网络到业务层逐级收敛的排查方法。示例统一使用https://api.example.com和sk-example-key实际使用时应替换为自己有权访问的 API 地址和密钥。本文整理自实际 API 网关维护过程中积累的故障排查记录重点说明可复用的通用诊断方法。先判断错误发生在哪一层一次 API 请求通常会经过以下几个层级DNS 解析TCP 与 TLS 连接网关鉴权路由与模型权限请求格式转换上游模型服务响应回传与客户端解析。如果连 HTTP 状态码都没有得到问题通常发生在前三层之前例如 DNS、TLS、代理或客户端超时。如果已经收到结构化 JSON 错误则说明请求至少到达了某个 HTTP 服务此时应优先阅读响应体而不是只看状态码。可以先执行一个不携带密钥的连通性检查curl-I--connect-timeout10https://api.example.com/返回200、301、401或404都能证明 DNS、TCP、TLS 和 HTTP 基本可达。这里的目标不是验证模型可用而是先把网络故障与业务故障分开。以 FishAI API 网关 为例根地址能够正常打开只能说明 HTTP 服务可达模型调用仍需使用对应的 API 路径并完成鉴权和模型权限检查。401请求没有通过身份验证401 Unauthorized通常表示服务端没有识别出有效身份。常见原因包括请求头没有携带密钥密钥前后带有空格或换行环境变量没有被当前进程读取使用了错误的鉴权头密钥已被禁用、撤销或过期Base URL 指向了另一个服务。在OpenAI兼容接口中常见请求头是Authorization: Bearer sk-example-key可以先查询模型列表curl-ihttps://api.example.com/v1/models\-HAuthorization: Bearer$API_KEY排查时不要把完整密钥输出到终端共享记录、工单或截图中。只需要确认变量长度、前缀和请求头是否存在。若命令行请求成功而客户端仍返回401重点检查客户端读取的是哪个环境变量以及旧进程是否仍保留旧值。403身份有效但没有当前操作权限403 Forbidden与401的区别在于服务端通常已经识别出调用者但拒绝当前操作。常见原因包括当前令牌没有目标模型权限令牌绑定的分组与模型所在分组不一致账号、项目或组织没有相应能力来源 IP、区域或访问策略受限目标接口不允许当前令牌使用请求触发了内容或安全策略。此时反复生成同类密钥通常没有帮助。应先记录响应体中的错误类型、错误消息和请求标识再核对令牌绑定范围与目标模型是否一致。如果/v1/models能看到模型但调用仍返回403只能证明模型对令牌“可见”不能证明当前协议、分组和操作全部被授权。404优先检查完整请求地址404 Not Found不一定表示模型不存在。它也可能表示路径拼接错误、接口协议不匹配或路由没有注册。常见错误地址包括https://api.example.com/v1/v1/chat/completions https://api.example.com/chat/completions https://api.example.com/v1/messages排查时需要记录客户端最终发送的完整 URL并确认Base URL 是否已经包含/v1客户端是否还会自动追加/v1Chat Completions、Responses 和 Messages 路径是否混用请求是否被发送到旧域名或默认域名反向代理是否把 API 路径改写到前端页面。如果响应体包含model_not_found再继续检查模型 ID、别名、权限和渠道映射。不要仅凭 HTTP404就认定模型下线。429区分请求频率与可用额度429 Too Many Requests常见于限流但不同服务也可能用它表示额度不足。因此需要结合错误消息和响应头判断。两类情况的处理方式不同类型常见表现处理方向请求频率过高短时间并发较多稍后重试恢复降低并发、增加退避、限制重试次数配额或额度不足持续返回失败不随等待恢复检查账号、项目、令牌或计费状态建议客户端采用带抖动的指数退避但必须设置最大重试次数。无条件立即重试会放大流量在网关与上游之间形成重试风暴。一个简单的退避顺序可以是1 秒 → 2 秒 → 4 秒 → 8 秒若响应包含Retry-After应优先遵循服务端提示。对非幂等请求还要确认重试是否会重复创建任务或重复计费。400 与 422请求格式或参数不被接受400 Bad Request和422 Unprocessable Entity常见于请求体格式正确但字段内容不符合接口要求。重点检查JSON 是否完整且可以解析model是否为空或拼写错误messages、input等字段是否符合当前协议可选参数是否被客户端错误转换是否发送了目标模型不支持的参数图片、音频或文件字段是否满足格式和大小要求。排查时应先删除温度、采样、响应格式和工具定义等可选字段只保留模型与一条短消息。最小请求成功后再逐项恢复参数通常可以快速找到不兼容字段。500、502、503 与 504区分网关和上游故障5xx表示服务端链路未能正常完成请求但不同状态码反映的阶段不同。状态码常见含义优先检查500服务内部异常错误日志、请求体转换、空值或未处理异常502上游返回无效响应或连接被断开上游地址、TLS、响应格式、代理链路503暂无可用服务或渠道渠道健康、模型映射、并发与熔断状态504等待上游响应超时上游延迟、网关超时、客户端超时配置收到502或504时不应马上判断为客户端配置错误。可以用相同密钥和最小请求复现并记录请求时间、返回状态、请求标识和总耗时。如果偶发成功、偶发超时还要比较不同时间段和不同上游渠道的表现。建立一个最小请求基线排查复杂客户端之前建议先使用curl建立一个最小可复现请求curl-ihttps://api.example.com/v1/chat/completions\-HAuthorization: Bearer$API_KEY\-HContent-Type: application/json\-d{ model: current-model-id, messages: [ {role: user, content: 只回复 OK} ], stream: false }这个请求应满足使用准确的模型 ID只有一条短消息不启用流式输出不包含工具调用不设置不必要的生成参数。如果最小请求成功而完整客户端失败就可以把问题缩小到客户端配置、附加字段或协议能力。若最小请求也失败则继续检查网关、模型权限和上游链路。建议记录哪些诊断信息一条可复现的问题记录至少应包含请求时间与时区请求方法和完整路径HTTP 状态码错误类型与错误消息请求标识或追踪标识使用的模型 ID是否为流式输出总耗时是否经过本地代理或企业网络。不要记录完整 API Key、用户原始提示词或含隐私的数据。诊断信息应足以定位链路同时避免扩大密钥和业务数据的暴露范围。一套可复用的排查顺序遇到 API 请求失败时可以按以下顺序处理确认 DNS、TLS 和 HTTP 是否可达保存完整状态码和结构化错误信息核对最终请求 URL 与协议路径验证鉴权头和环境变量查询令牌可见的模型列表使用准确模型 ID 发送最小请求再逐项恢复流式输出、工具调用和其他可选参数对5xx记录请求标识、耗时与复现时间对429区分限流和额度问题控制重试次数。总结状态码不是最终结论而是定位故障层级的起点。401主要检查鉴权403主要检查权限404优先检查完整路径429需要区分限流与额度5xx则要继续区分网关内部、上游连接和超时问题。先建立一个可复现的最小请求再逐步恢复复杂参数比直接更换模型、密钥或客户端更容易找到真正原因。完整记录请求路径、错误体、请求标识和耗时也能显著提高后续排查效率。