API 超时后要不要重试？SDK 自动重试与重复请求排查
API 超时后，先确认超时发生在哪一层、SDK 是否已经重试，以及服务端结果能否查明，再决定是否补发。没收到结果不能证明请求没执行或没计费；已经完成的模型调用，也不应因下游写入失败而整项重跑。本文核对日期为 2026-10-25，讨论客户端决策，没有对云岚API做真实调用或幂等能力测试。
这个 timeout 到底限制了什么？
以当前 HTTPX2 文档为例，各阶段超时含义不同：
| 类型 | 等待什么 | 优先检查 |
|---|---|---|
| connect | 与目标建立连接 | 地址、网络、代理和连接错误 |
| read | 收到下一块数据 | 首块或后续块的等待，不能直接当作总生成时间 |
| write | 发出一块请求数据 | 上传、网络及请求是否可能部分发送 |
| pool | 从连接池取得连接 | 本地并发和连接占用，不直接归因于模型慢 |
这些计时器不能替代整个逻辑任务的总截止时间。应用还要把排队、所有尝试和退避等待纳入自己的时限，并在到期后停止安排新尝试、处理正在等待的调用；本地取消不等于已撤销服务端工作。HTTPX2 超时定义、AWS 重试与副作用说明
流式持续收到数据可能避免读取超时，却仍耗时很长。若已收到部分文字，先保留为未确认状态，按SSE 完成判断检查终态，不能靠反复重连拼成一次“成功”。
你只调用一次，SDK 可能已经尝试多次
本次核对的 OpenAI Python SDK 官方源码版本为 3.37.0。其文档说明：连接错误、408、409、429 和 5xx 等符合条件的错误默认最多自动重试两次，超时也在默认重试范围；请求体还须能安全重发。max_retries=0 可关闭这一层自动重试，timeout 配置等待限制。固定源码版本的重试与超时说明
先记录实际安装版本和生效配置，再查看框架、队列、网关是否另有重试。若应用决定统一控制次数，可以关闭 SDK 层并显式处理错误；只改 SDK 不能关闭其他层。
例如，假设外层共调用两次 SDK，每次都耗尽“两次重试”，则最多有 2 × (1 + 2) = 6 次该 SDK 的 HTTP 尝试。这是条件算例，不是现场请求数；有些尝试可能没到上游，其他层也可能再放大。不能把六次尝试直接换算成六次生成或六笔扣费。
先分清结果，再决定是否补发
| 当前证据 | 下一步 |
|---|---|
| 已确认上游完成，结果已保存 | 复用结果，处理尚未完成的下游步骤 |
| 明确的认证、参数或权限错误 | 修配置；原样重试不会修复这些问题 |
| 明确临时错误，已确认可重试条件 | 遵守服务等待要求，有限退避，并检查次数、费用与剩余时限 |
| 写入超时、读超时或断流，执行结果未知 | 查任务状态、请求记录及账单；保留未知，不立即整项重跑 |
重试前必须确认该操作的重复执行语义。HTTP 的 POST 本身不保证幂等；只有服务明确提供相应机制，或能确认原操作未应用等条件下，才能据此设计自动重试。SDK 能重放请求体，不等于服务端保证只执行一次。RFC 9110 的重试边界
若有 Retry-After，不要为赶截止时间而提前重试；等待超出剩余预算时，留待后续处理。具体错误码按报错排查解释；缺日志也不能单独证明请求未到达。
怎样避免重复请求变成重复写入？
为逻辑任务保留稳定业务键和输入版本，为每次尝试另记编号。服务返回的 request ID 用来定位请求，不是自动去重凭据；是否支持幂等键、有效期及相同键的请求体要求，都要查目标服务的明确约定。SDK 请求标识说明
把“模型结果已验收”和“业务结果已写入”分开保存。下游用业务键、版本和操作类型配合数据库原子唯一约束，或接收方真正支持的幂等机制处理重复；只做“先查不存在再写”仍可能在并发时重复。若外部写入结果也未知，先核对目标系统，不把它当作重新调用模型的理由。
下载超时与重试检查包，逐次记录配置、错误阶段、上游状态和下游状态。包内为静态清单、空白 CSV 与人工案例，不会发请求。n8n 接入继续看工作流验收，异步任务看Batch 对账，实际扣费按账单明细核对。
常见问题
把 timeout 调大就能解决吗？
只可能改变等待行为。先分清连接、读取或连接池问题，再根据任务时限调整；它不能修复错误地址、权限或重复执行。
关闭 SDK 重试就绝不会重复吗？
不能。队列重投、外层循环、网关和人工重跑都可能再次发请求，下游也需要独立控制重复写入。
用同一个 request ID 重试就能去重吗？
不能这样推定。诊断标识和服务端幂等协议是两回事，重复使用一个自定义标识不会自动建立去重规则。
超时却查到扣费，是不是异常？
先按时间、模型、请求记录和实际计费规则核对。客户端未取得结果，不能证明服务端没执行；记录不足时保留待核查，不先认定正常或错误。