AI API 请求超时后能不能直接重试？幂等键、补偿和失败分类
AI API 接入遇到请求超时，不要先盲目重试，应区分连接失败、服务端超时、限流和业务写入结果，再用幂等键与补偿机制避免重复执行。
真实问题
开发者最容易误判的一类故障，是把“客户端没等到响应”直接等同于“模型没有处理请求”。例如一个 AI 自动化办公任务提交摘要请求，网关在 30 秒时断开连接，但上游模型可能已经生成完成，甚至业务系统已经把结果写入队列。此时用户点击重试，就可能得到两份摘要、两次扣费，或者同一封通知被写入两次。
永沃云枢在 https://ai.jn83.com 整理 AI 模型接口接入经验时，会先问三个问题：请求有没有唯一标识，服务端能不能查询结果，业务写入是否具备幂等保护。Codex 接入和开发者 AI 调用都应把这三个问题放在重试按钮之前。
适用场景
适合长文本生成、代码解释、批量摘要、文件分析、客服草稿和 AI 自动化办公任务。尤其适合请求完成后还要写数据库、发消息、更新工单或生成文件的流程。单纯的只读问答可以采用较简单的重试，但涉及资金、库存、订单、对外通知和权限变更时，必须先确认原请求状态。
如果使用 CCSwitch 配置多个 AI 模型接口，还要把 profile、模型名和请求策略写进追踪记录。不同供应商的超时、错误码和重试建议可能不同，不能把所有失败都套同一套规则。
操作步骤
第一步，为每次调用生成稳定的 request_id 和业务侧 idempotency_key，前者用于日志追踪，后者用于防止重复执行。第二步，把失败分成连接未建立、请求已发送但无响应、服务端明确 4xx、服务端明确 5xx、限流和业务写入未知六类。第三步，只有明确可重试的类别才进入退避队列，例如短暂 502、连接重置或 429；参数错误、权限错误和模型不存在应直接失败并提示修正。
第四步，为每个请求设置重试预算，记录第几次重试、等待时间和最终状态，不要让前端按钮无限触发。第五步，给“结果未知”保留查询接口：先用 request_id 查询上游或本地任务表，确认不存在结果后再重试。第六步，模型返回成功后，业务写入仍要使用幂等键，避免模型层成功、数据库层重试时重复落库。
排错路径
如果日志显示客户端超时但上游有完成记录，问题在响应链路，不应重新提交模型请求。若上游没有记录而网关有发送记录，检查代理是否在请求体上传完前断开。若连续出现 429，查看请求是否被多个 worker 同时重试，退避时间是否带随机抖动。若文本结果只有一份但账单出现两次，检查是否生成了两次不同的请求 ID。
排查时至少关联 request_id、idempotency_key、model、profile、开始时间、首字节时间、结束时间、错误类别和业务写入状态。不要只看 HTTP 状态码，因为超时往往没有可用的状态码。可以让 Codex 根据日志生成失败分类表，但最终的重试白名单应由开发者确认。
常见问题 / 避坑
问：超时后等几秒再重试就可以吗？不一定，先判断请求是否已经到达上游。问：所有 5xx 都能重试吗？不应一概而论，连续重试可能放大故障，应该设置预算和熔断。问：幂等键能防止重复扣费吗？它只能帮助服务端识别重复请求，是否扣费仍要以具体接口的实现和账单记录为准。问：前端能不能直接发起重试？可以触发，但应由后端统一生成策略并记录次数。
检查清单
检查每次 AI API 调用都有 request_id；检查有独立的幂等键；检查超时和明确失败被分开；检查 429、5xx 和网络错误有不同退避策略；检查参数错误不会自动重试；检查未知结果可以查询；检查业务写入具备幂等保护；检查日志能关联 CCSwitch 配置、模型名和最终状态；检查重试预算和人工介入条件已写进运行手册。
验收与复盘
上线前可以故意制造四种故障：连接建立前断开、响应中途断开、返回 429、模型已完成但业务写入失败。验收时观察系统是否只在允许的类别重试，是否保留同一个幂等键，是否能从日志找回原请求。复盘不要只记录“重试成功”，还要记录重复执行风险、额外成本、用户看到的提示和人工接管入口。这样 AI 模型接口接入才是可管理的调用流程，而不是把不确定性藏在按钮后面。