AI API 调用错误排查：401、403、404、429 与 5xx｜ModelPort
ModelPort 编辑 · 更新于
先区分本地网关与上游，再决定修正鉴权、等待额度窗口或联系支持。记录端点、模型 ID、时间、是否流式、错误信息和请求标识（如有），不要提交完整密钥或敏感内容。
401：先查本地鉴权
确认使用完整的 Authorization: Bearer、x-api-key 或 x-goog-api-key 请求头，并检查密钥存在、未停用，关联用户仍可用。缺少或无效密钥、密钥被禁用、用户不可用会在本地鉴权阶段拦截；查询参数形式的密钥已被拒绝。
403：查访问范围与额度门槛
检查分组是否启用、用户是否获准使用该组及 IP 限制。普通按量密钥余额耗尽、密钥过期、订阅缺失或状态不合格通常是 403；自动路由切到下一组前也会重新检查该组授权。余额问题不能靠重复请求解决。
404：查模型、分组和端点
核对精确模型 ID、大小写和路径。分组白名单未列出的模型会在路由改写前拒绝；自动分组找不到登记该模型的已启用候选组，也会返回模型不存在类错误；当前平台不支持该端点同样可能是 404。客户端可选不代表当前密钥可调用。
429：区分本地与上游限流
本地 429 可能来自密钥额度、用户或分组 RPM、订阅日/周/月窗口、并发等待队列等，应查看账户、订阅和用量记录。上游 429 也会映射为限流响应，并在可用时保留 Retry-After；有该头就按它等待，没有就降低并发，避免紧密循环。
5xx：定位服务端还是上游
自动分组目录、计费服务等本地依赖故障会产生 5xx；上游 500、502、503、504 或过载也会转换成服务端错误。上游鉴权/访问拒绝不一定原样呈现为客户端 401/403，默认路径会记录上游状态并返回网关上游错误。看到 502/503，先保留时间和响应信息，不要立即重置密钥或反复充值。
不要盲目重试
自动分组只在响应未提交且故障被标记可重试时切换；普通 4xx、参数错误和已提交的流式响应不会自动重放。流式已经输出后，同一个请求不能重试到下一组；自行重发属于新请求，先核对请求标识与站内记录。