AI API 调用失败后要不要自动重试？
AI API 接入业务系统以后，失败处理往往比第一次调通更重要。网络抖动、模型超时、限流、参数错误、客户端中断都可能表现成“没有拿到结果”，但它们对应的处理方式完全不同。直接无限重试，可能造成重复扣费、重复生成、重复写库，最后排查成本比失败本身更高。
适用场景：调用会失败，但业务不能乱
这篇适合已经把模型能力接进客服分流、内容审核、合同摘要、工单分类、批量改写或开发者 AI 调用的团队。你可能遇到过接口偶发 429、502、客户端超时，或者前端提示失败但后台实际拿到了结果。若还没有建立用量观测，先参考 AI API 接入后怎么知道谁在消耗额度，把 request_id、用户、功能和模型名打通。若问题是流式输出中断，可对照 AI API 流式输出中断排查 单独处理。
操作步骤：先判断错误，再决定重试方式
1. 给每次请求生成业务幂等键
不要只依赖接口返回的请求编号。业务侧应在发起调用前生成一个稳定的 idempotency_key，例如用户 ID、任务类型、源记录 ID、提示词版本和批次号的组合。这样前端刷新、队列重复投递、Codex 脚本二次执行时，系统能识别“这是同一个任务”，而不是创建两个摘要或两次审核记录。
idempotency_key = sha256(user_id + task_type + source_id + prompt_version)
request_id = new_uuid()
status = pending | running | succeeded | retryable_failed | final_failed2. 按错误类型分层处理
参数错误、模型名不存在、Key 无权限通常不该自动重试，应该进入配置检查。429、网关超时、连接重置可以短次数退避重试。返回内容格式不合格时，要先看是否是提示词契约问题，可结合 开发者调用 AI 模型时怎么约定 JSON 输出，把校验失败和接口失败分开记录。
3. 用退避和预算保护系统
重试不是越快越好。建议采用 1 秒、3 秒、10 秒这类退避节奏，并设置单任务最大尝试次数、单用户分钟级预算、单功能日预算。失败结果不要混进成功缓存，也不要让队列在半夜无限补偿。对批量 AI 自动化办公任务，先让少量样本跑通，再放大批次。
4. 补偿队列要能人工查看
有些任务不适合自动补偿，比如合同条款摘要、客户投诉分级、金额相关说明。它们失败后应进入可视化队列，展示源记录、脱敏输入、错误类型、已尝试次数、下一步建议和负责人。涉及敏感字段时，先按 AI API 接入前的敏感字段处理 做最小化和日志留存控制。
常见问题/避坑：超时不等于模型没处理
第一个坑是把客户端超时当成服务端失败。前端等不到响应时，模型侧可能已经生成完成，业务侧也可能已经写入了结果。第二个坑是重试时重新生成提示词版本，导致同一个任务得到不同答案。第三个坑是只在成功时落库，失败时没有状态，后续不知道是否已经尝试过。第四个坑是把所有错误都显示成“网络异常”，用户会反复点击提交。
还有一个容易忽略的成本坑：失败重试也会消耗额度。模型调用管理不能只看成功次数，还要记录失败次数、重试次数、空响应和格式校验失败。若正在做多模型备用，可参考 AI 模型接口多模型备用，把切换模型和重复重试分开设计。
检查清单：上线前验证五条路径
- 同一个业务任务重复提交两次，系统只保留一条最终结果。
- 模拟 429 或网关超时，确认退避次数、间隔和最大尝试次数符合预期。
- 模拟模型名错误或 Key 无权限，确认不会自动重试，而是提示配置排查。
- 模拟格式校验失败，确认记录提示词版本、原始输出摘要和校验错误。
- 检查日志不出现敏感原文，并能用 request_id 串起调用、重试和结果。
FAQ：所有 AI API 调用都要做幂等吗
只要结果会写入业务系统、触发后续流程或影响用户余额，就应该做幂等。临时问答、纯本地测试可以简化，但正式的客服分流、批量内容处理、资料入库、开发者 AI 调用和 Codex 接入脚本都建议保留幂等键。幂等不是为了把系统做复杂，而是为了失败后能判断“要不要继续”。
验收标准：失败可追踪，重试不重复
一次合格的 AI API 重试设计，应能回答四个问题：这次失败属于哪一类，是否已经产生业务结果，是否允许自动重试，重试后如何避免重复写入。上线前可以准备三种样本：短文本分类、长文本摘要、批量改写。分别触发成功、超时和参数错误，检查状态表、日志、前端提示和补偿队列。
如果团队通过 CCSwitch 配置多个模型，也要明确哪些错误由 CCSwitch 配置排查解决，哪些错误由业务重试处理。配置错了模型名，不应该让队列一直重试；真实的限流或临时超时，才适合退避。永沃云枢建议把幂等键、request_id、提示词版本、模型名和业务记录 ID 放在同一条日志里，这样 https://ai.jn83.com 上的 AI 模型接口接入流程更容易被长期维护。