AI 模型接口报错怎么排查？
接口报错时不要只反复换模型。先看状态码，再看 API 地址、Key、模型名、网络和重试策略，排查速度会稳定很多。
先确认错误属于哪一类
开发者 AI 调用失败时，最常见的误区是只盯着返回内容里的最后一句话。实际上，状态码通常已经给了方向。401 多数是 Key 不正确或没有生效，403 可能是权限或账户状态问题，404 常见于模型名、路径或 API 地址写错，429 通常和频率、并发或额度有关，5xx 更可能是服务端或上游暂时异常。
新手搜索“GPT 中转”时，往往是在找一个能把请求转给模型的入口。更准确地说，你需要检查的是 AI 模型接口接入与调用管理：请求是否发到正确地址，鉴权是否通过，模型名是否存在，失败后是否有合理重试。
第一步：用最小请求复现
不要一开始就在完整业务系统里排查。先用最小请求测试 API 地址、Key 和模型名，只保留一段简单输入。成功后再回到 Codex、CCSwitch 或业务代码里检查配置。如果最小请求都失败，问题大概率不在你的业务逻辑。
记录复现结果时，至少保存请求时间、接口地址、模型名、状态码、错误摘要和请求来源。不要把完整 Key 写入记录，只保留前后少量字符用于识别。团队场景可以结合 多人模型调用管理清单，让每个失败请求都能定位到负责人。
第二步：检查配置细节
API 地址要注意结尾路径和协议，模型名要和服务端可用名称一致，Key 要确认没有多余空格和换行。CCSwitch 配置里如果同时维护多个模型，建议先只保留一个可用模型做验证，避免在切换时把错误来源混在一起。注册后首次配置可以参考 CCSwitch API 地址和模型名检查清单。
如果报错只出现在 Codex 中，检查本机环境变量、代理设置、工作目录和插件权限。Codex 接入不是单纯填一个 Key，它还依赖本机网络、命令执行权限和当前任务上下文。能在最小请求里成功，不代表业务脚本和本机工具都已经配置正确。
第三步：设置重试和降级
429、网络超时和偶发 5xx 可以配置有限重试，但不要无限循环。建议使用退避策略：第一次等待 2 秒，第二次等待 5 秒，第三次失败后记录日志并停止。对用户可见任务，要给出明确提示；对后台任务，要把失败任务放入待复核队列。
不要把所有错误都交给重试处理。401、403、404 这类配置错误通常重试也不会好，只会增加无效调用。模型调用管理的关键是区分“可以再试”和“必须改配置”。
排查清单
- 最小请求能否成功返回。
- API 地址、路径、模型名和 Key 来源是否一致。
- CCSwitch 配置是否只保留一个模型做初次验证。
- 日志是否包含状态码、耗时、错误摘要和请求入口。
- 重试次数是否有限，并能在失败后进入人工复核。
什么时候该停下来
如果连续三次都得到同一类配置错误，不要继续换提示词或加重试。先回到账号、模型名、API 地址和权限检查。若错误与额度或调用频率有关，再去看 AI API 接入后的额度与模型选择清单，把高频调用入口单独复盘。