AI API 报错排查指南：从请求失败到稳定恢复

API 调用失败时，直接换模型或反复重发请求，常常只会让问题更难定位。更有效的顺序是先确认失败发生在哪一层，再判断它是否值得重试。

第一步：保留必要的错误现场#

记录请求时间、接口路径、模型标识、HTTP 状态、错误码、请求标识和耗时。如果经过自有服务端或网关，应尽量保留各层用于关联的请求标识。

日志不要包含可用密钥。用户输入与输出也不应无差别记录；优先保存定位问题所需的最小信息，对敏感内容做脱敏。向支持人员反馈时提供已经过滤的错误响应，而不是完整密钥截图。

第二步：先看地址和协议#

检查 API 地址是否多拼了 /v1，请求方法是否正确，Content-Type 是否与请求体一致，以及模型是否支持当前接口。一个文本模型的请求格式不能直接套用到专用视频接口。

如果返回的是 HTML 而不是预期的 JSON，优先检查是否打到了网站页面、反向代理错误页或登录页。此时继续调整提示词不会解决问题。

第三步：结合响应体理解状态码#

下面是常见 HTTP 含义，具体判断仍应以当前接口的错误码和响应体为准；网关与上游服务可能采用不同的映射方式。

不要只用状态码猜原因。例如，同为 429，短时并发限制和需要调整配额的情况，处理方式可能完全不同。

第四步：缩小到最小可复现请求#

将请求简化为一个已确认可用的模型、一条短文本，以及文档要求的必要字段。移除工具、附件、复杂格式和多轮历史后，再逐项加回。

每次只修改一个变量，并记录结果。这样可以区分是某个参数不受支持、素材不可访问，还是整体链路存在问题。排错请求也会实际消耗服务资源，因此应控制尝试次数。

第五步：为重试设置边界#

只对可恢复的临时错误重试。采用逐步延长的等待时间，加入少量随机抖动，并限制尝试次数与总截止时间；接口给出 Retry-After 等等待提示时，应按其含义处理。

特别注意生成请求的副作用：网络超时不代表服务端没有执行。异步任务应先查询已有任务，已经收到部分流式内容时也不宜静默重发。只有接口明确支持并规定幂等机制时，才能按其文档使用，不能自行假设重复请求会自动合并。

把故障转化为可恢复的体验#

界面应保留用户输入，区分失败与状态待确认，并提供明确的下一步。已经生成的部分内容可以保留，但应标记不完整。

服务端则需要观察错误类型、请求成功率和等待时间的变化。对持续异常及时停止无效尝试，避免重试流量挤占正常请求。流式场景可继续阅读流式输出接入指南，异步视频场景参考视频生成工作流。