模型 API 重试与退避模式入门指南

步骤一：先区分值得重试的模型 API 错误

重试的目标是处理短暂故障，而不是重复执行必然失败的请求。网络连接超时、连接被重置、HTTP 429 限流响应，以及多数 HTTP 5xx 服务端错误，通常可以进入重试流程。HTTP 400、401、403、404 等请求或授权错误，往往需要修正参数、凭据或模型名称，直接重试只会增加流量和费用。

调用模型 API 时，还要区分“请求未送达”和“结果未成功返回”。如果客户端超时，但服务端实际上已经开始处理请求，盲目重发可能造成重复写入。对于创建订单、保存对话或调用外部工具等有副作用的操作，应使用幂等键，或在重试前查询该请求是否已经完成。

步骤二：为每类失败设置明确的重试上限

不要写无限重试循环。先为一次调用设置有限次数，例如首次请求之外再尝试两到四次，并为整个操作设置总超时时间。单次请求超时、重试次数和总时限需要一起设计，否则多个短超时可能在用户已经放弃页面后仍持续占用资源。

• 对于 429 响应，应优先读取服务端返回的 Retry-After 或等价提示，并在指定时间后再发起请求。
• 对于 5xx 和短暂网络错误，可以重试，但应记录状态码、错误类型和最终结果，便于判断是否需要调整策略。
• 对于流式响应中断，应根据业务决定是否从头重试，避免把已展示的内容与重试结果直接拼接。
• 对于上下文过长、参数校验失败和余额不足等确定性错误，应停止重试并向调用方返回可处理的错误信息。

步骤三：使用指数退避降低集中重试压力

固定间隔重试容易让大量客户端在同一时刻再次发请求，限流或服务波动时会形成重试风暴。指数退避会逐步拉长等待时间，例如以 500 毫秒为基础，后续等待约为 1 秒、2 秒、4 秒。实际实现中应设置最大等待上限，防止单次调用拖延过久。

指数退避适合 Claude Opus 5.5 或 Gemini 3.1 Pro 这类可能需要较长生成时间的调用，但等待值仍应由应用的交互需求决定。面向实时聊天的接口通常需要更短的总时限；后台批处理则可以允许更长的等待和更多的排队。

步骤四：在退避时间中加入随机抖动

仅使用指数退避仍可能让同一批任务按相同节奏重试。加入随机抖动可以打散请求，例如在计算出的等待时间内随机选择一个值，或在基础等待时间附近增加随机偏移。实现时应保证等待时间非负，并保留最大等待上限。

抖动不应替代限速。客户端还应限制并发数和单位时间内的发送量，尤其是在多个工作线程共享同一组 API 凭据时。将并发控制放在请求入口处，通常比让大量请求先失败再重试更节省成本。

步骤五：为模型调用保留可观测的重试记录

每次调用至少记录请求标识、目标模型、尝试次数、等待时长、错误类别和最终状态。日志中不要保存 API 密钥、完整用户提示词或可能包含敏感数据的模型输出。通过这些记录，团队可以识别是特定模型、网络路径、并发设置还是输入规模导致失败率上升。

当连续失败达到阈值时，可以启用熔断：暂时停止向异常上游发送新请求，快速返回可理解的降级结果，并在一段时间后用少量探测请求恢复。熔断适合保护应用自身，不应把它当成掩盖配置错误的手段。

步骤六：在统一入口中封装重试策略

将超时、错误分类、退避、抖动、幂等键和日志封装在一个客户端包装层中，避免每个业务模块各自实现一套不同规则。这样切换模型或 SDK 时也更容易保持一致。对使用 OpenAI SDK 的应用，可将 API 基址配置为 https://api.api365relay.com/v1；其他兼容场景应按所用客户端的基址规则配置。

如果团队需要在多种模型之间试用和调度，Relay365 适合作为按量付费的统一中转入口，可用于 Claude Code、Codex、Gemini CLI 及 OpenAI SDK 兼容客户端。建议在完成本地错误处理测试后创建一个 Relay365 账户，再用小流量验证限流、超时和重试日志是否符合预期。成员邀请他人付费时也可以获得推荐奖励，但推荐机制不应影响模型选择和故障处理策略。