AI API 报错与重试:别让一个问题变成两个
区分需要修改的请求和可以重试的故障,避免异步任务被重复创建。

重复之前先看清失败原因
请求格式错误、密钥无效或参数不受支持,通常需要修改配置,而不是原样再发一次。对于限流或暂时性服务错误,可按接口文档判断是否重试。记录状态和请求标识,但不要把凭据或敏感提示词写进日志。
认证或权限错误需要检查密钥与访问范围;请求格式、模型名称或参数错误需要修改输入;限流与部分临时服务故障可能适合稍后重试。具体状态码和错误内容以接口文档为准。把这些情况全部归为“网络异常”会让用户和开发者都失去有用线索,也容易触发没有意义的重复请求。
给暂时性故障恢复的时间
对于适合重试的故障,设置有上限的重试次数、退避和随机抖动;服务端提供等待时间时也应遵守。设置整体截止时间,别让用户无限等待。不要对所有错误一律重试,也要避免大量客户端在同一瞬间再次请求。
对文档允许重试的情况,可以限制次数和总耗时,逐步增加等待时间,并加入随机抖动,减少多个客户端同时重试造成的压力。服务端提供明确等待时间时应优先遵守。一个合理的策略还要允许用户取消,并在达到上限后结束,而不是在后台无期限地消耗资源。
遇到暂时性故障时,等待后再按受控策略重试。有副作用的任务要格外小心
应用收到超时时,远端可能已经接受请求。再次创建图片或视频任务可能重复执行并产生费用。接口返回任务标识后应保存,重新提交前先查询状态;只有接口明确支持时,才依赖其幂等机制。
提交生成任务后发生超时,可能只是响应没有及时到达,远端任务却已经创建。拿到任务 ID 时先保存并查询;没有拿到 ID 时,不要假设任务一定不存在。检查接口是否提供查询、回调或明确的幂等机制,并按文档处理未知状态。只有在了解可能的额外费用后,才发起新的创建请求。
给等待的人一个明确的下一步
告诉用户应该重试、修改输入还是稍后再试。适当保留已显示的流式内容,并说明它尚未完成。分别测试无效请求、限流、网络中断和任务延迟,它们不应全部显示成同一个含糊的错误。
记录时间、请求标识、接口、状态码、耗时和必要的错误类别,通常足以开始排查。不要写入完整密钥、授权头或不必要的用户提示词;分享日志前还应检查个人信息。把客户端可见提示与内部诊断信息区分开:用户需要知道下一步,维护者则需要可追踪的上下文。
在测试环境分别模拟无效参数、身份验证失败、限流、连接中断和处理缓慢的异步任务。观察是否只对合适的错误重试、等待时间是否有上限、界面是否保留部分结果。还应检查用户连续点击重试时是否会创建重复任务。演练不需要真实客户数据,也不应向生产环境发送会产生费用的任务。
先判断失败属于哪一类
当请求失败时,先保留状态码、请求标识、发生时间和脱敏后的错误类型。认证失败通常需要检查密钥、权限或账户配置;请求格式和参数错误需要修改输入;限流与临时服务故障则可能适合稍后重试。具体行为以接口文档和实际响应为准,不要把每一种错误都塞进同一个自动重试循环。
网络超时尤其需要区分发生阶段。如果连接尚未建立,服务可能没有收到请求;如果请求已经发送而响应丢失,服务可能正在处理,甚至已经完成。客户端看到的超时不能单独证明远端没有执行。对创建任务、发送消息或修改数据的操作,这个区别会影响重复执行和费用。
错误提示要对用户有帮助,同时避免暴露密钥、内部地址或原始堆栈。可以说明操作没有完成、是否保留了已输入内容、用户是否可以稍后再试。对需要支持团队排查的问题,提供请求标识比让用户截图完整敏感内容更合适。
给重试设置边界
对于明确可重试的暂时性错误,可以设置最大次数和总等待时间,并随着重试次数增加等待间隔。加入随机抖动有助于避免大量客户端在同一时刻再次请求。若响应或文档提供等待建议,应优先按照其规则处理;不要把一个固定的演示数字当成所有服务的通用限制。
在多层系统中尤其要注意重试叠加:浏览器、业务服务和客户端库如果各自重试,最终请求次数可能远大于预期。尽量明确由哪一层负责,并记录每次尝试的结果。超过限制后停止并返回可理解的状态,避免长时间占用连接或让用户以为操作仍然顺利进行。
只读查询通常比创建操作更容易安全重试,但仍需遵守接口限制。有副作用的请求应使用服务实际支持的幂等机制,或者先查询已知任务状态。不要自行声称任意接口都支持幂等键;如果没有可靠的去重方式,就应明确提示用户并谨慎处理不确定结果。
用两个例子检验策略
第一种情况:用户发送文本请求,服务明确返回限流提示。应用可以保留输入,按照允许的等待时间和重试上限尝试恢复,并在等待期间让用户取消。如果多次尝试仍失败,说明现在无法完成,而不是无限显示加载动画。
第二种情况:用户提交视频生成后,网络在返回任务标识前中断。此时应用不能确定任务是否已经创建。应使用接口支持的查询或恢复方式核实;如果无法核实,清楚告知用户状态不确定,避免后台悄悄重复创建多个任务。重新生成是否收费应以实际规则为准。
把这两类情况加入自动化测试,再加入无效密钥、错误参数、连接中断和用户取消。核对每一层的尝试次数、最终提示和日志是否符合预期。好的重试策略不是尽可能多地重发,而是在恢复机会、用户体验和重复操作风险之间保持清晰的边界。
最后,不要忘记检查告警本身:如果每次暂时性失败都触发高优先级通知,团队很快会忽略真正的问题。按持续时间、影响范围和是否自动恢复区分告警等级,并定期回看哪些重试实际上解决了问题。
两种失败,两种处理
如果请求被限流,且服务返回了重试等待时间,就在重试次数与总时限内按提示等待。如果视频创建请求在提交后超时,任务可能已经存在:先查找已保存的任务 ID 并查询状态。如果没有拿到 ID,应明确说明状态不确定,按接口文档处理,而不是假定再次提交不会产生费用。
用户联系支持时,优先请其提供发生时间、模型名称和请求标识,以及经过脱敏的错误说明。不要要求用户在公开渠道发送密钥或完整私人内容。维护者应根据记录核对请求是否已创建任务,再给出明确的排查步骤或安全的重试建议。