AI API 返回 401、429、500 怎么分工排查？
AI API 接入上线后，错误码会同时出现在前端提示、后端日志、网关记录和上游响应里。如果团队只说“接口又报错了”，很容易把 Key、限流、参数、上游异常和本地超时混在一起。更可靠的做法是建立错误码分诊表，让不同角色知道该看哪一层证据。
适用场景：用户只看到失败，后台看到一堆状态码
这篇适合已经把 AI 模型接口接到客服摘要、知识库问答、内容审核、自动化办公、内部 Codex 工具或批量脚本里的团队。常见现象是前端显示生成失败，后端日志有 401、403、429、500、502、504 或连接超时，但没有统一字段能说明是认证问题、预算问题还是上游波动。如果你的主要问题是排队和高峰限流，可以先看 AI API 突然限流怎么办；如果失败后要不要自动重试，再看 AI API 调用失败后要不要自动重试。
先分层：前端、业务服务、网关、模型接口
同一个 500，不一定来自模型供应方。前端可能因为连接断开显示失败，业务服务可能因为参数校验抛错，网关可能因为超时返回 504，上游 AI API 也可能返回自己的错误结构。排查时先把每次调用串起来：用户动作、业务 request_id、网关 trace_id、模型请求 ID、状态码、错误体摘要、耗时和重试次数。没有这些字段，就很难做真正的模型调用管理。
操作步骤：建立错误码分诊表
1. 401 和 403 先查认证与权限
401 通常先看 Key 是否为空、是否被旧环境变量覆盖、是否带了多余空格、是否请求了错误的 base_url。403 则更偏向权限、模型不可用或账户策略限制。检查命令可以从当前进程环境开始：
Get-ChildItem Env: | Where-Object { $_.Name -match 'OPENAI|API|BASE|MODEL' }
rg -n "OPENAI_API_KEY|BASE_URL|model" .如果你刚改过地址却仍请求旧接口，可以配合 Codex 调用的 API 地址为什么总是旧的 这类配置优先级思路检查。日志里不要输出完整 Key，只保留前后几位或哈希。
2. 429 查速率、并发和预算
429 不要只写“稍后重试”。先区分上游限流、团队额度、单用户次数、功能级并发和批量任务占满队列。日志里应包含队列名、排队时长、输入长度、模型名和用户标签。自动化办公场景尤其容易把批量文档处理和人工即时请求混在一个通道，导致用户感觉所有功能都坏了。限流时要先保护入口，再决定是否降级模型或暂停批量任务。
3. 400 和 422 查参数、提示词和输出约束
参数错误往往不是上游故障，而是本地拼装请求时传了空消息、错误模型名、超长上下文或不合法的 JSON schema。结构化输出要记录提示词版本、字段要求和失败样本。可参考 开发者调用 AI 模型时怎么约定 JSON 输出，把字段缺失、类型错误和解析失败分开。
4. 500、502、504 和超时要保留证据
服务器错误需要看发生在哪一层。业务服务 500 要查本地异常栈；网关 502/504 要查连接、代理和超时设置；上游 500 要记录返回体摘要和 request_id。不要在没有幂等键的情况下无限重试。对于流式输出，还要区分“上游还在返回、代理没刷新、前端没渲染、用户已取消”。相关路径可以看 AI API 流式输出页面卡住怎么办。
常见问题/避坑：给用户的提示也要分级
第一个坑是所有错误都提示“网络异常”，用户会重复点击，后台压力更大。第二个坑是把上游错误体完整透给用户，里面可能包含内部字段。第三个坑是只记录失败，不记录成功样本，后续无法比较同一模型、同一提示词的差异。第四个坑是客服和开发共用一张截图排查，却没有 request_id。永沃云枢建议把用户提示分成“可重试、需改输入、排队中、额度不足、系统处理中”五类，既保护体验，也方便后台复盘。
检查清单：每个错误至少有一条去向
- 401/403 是否能定位到 Key、base_url、模型权限或环境覆盖。
- 429 是否能看到队列、并发、预算、用户标签和退避策略。
- 400/422 是否能关联到参数、提示词版本、输入长度和输出结构。
- 500/502/504 是否区分本地服务、代理网关和上游 AI API。
- 前端提示是否避免泄露内部错误体，同时说明下一步动作。
- 日志是否包含 request_id、模型名、耗时、状态码和重试次数。
FAQ：什么时候该升级给人工处理？
如果同一用户连续遇到认证失败，要先查账户和 Key，不要让用户反复提交。如果同一功能在五分钟内集中出现 429，要暂停批量任务或降并发。如果上游 500 只影响某个模型，可以临时切换到经过验收的备用模型，但要记录质量差异。涉及敏感资料、合同、客户数据时，失败样本要脱敏后再进入排错文档。最终验收不是“错误消失一次”，而是错误码、日志、用户提示和重试策略能互相对上；同时把相关页面放进 AI API 接入专题、Codex 实操与 AI 资讯 和 帮助页，让新同事能沿着 https://ai.jn83.com 查到同一套规则。