哪些错误码可以重试：一份带具体参数和预算公式的 SDK 重试决策清单
结论先行："这个错误码能不能重试"不是一个网络问题，而是一个产品语义问题。同一个 504，对"查询订单"是安全的，对"创建订单"可能就是重复扣款。我 5 年技术 PM 经历里，经手过 2 起重试引发的资损事故，根因没有一起是"没加退避"，全是在写接口上对"结果未知"类错误码做了盲目重试。这篇把决策框架、错误码白名单、预算公式、SDK 默认参数一次讲清楚，可以直接抄。
一、现象：一次"网络抖动"，11 个用户被扣了两次款
先摆数字，免得大家各说各话。
去年我们一个支付类 B 端平台（日均 4.2 万笔代扣，客户端是团队自研的 Java SDK，底层 OkHttp 4.12），某次机房网络抖动 40 秒，SDK 的默认策略是"任何 5xx 和超时都自动重试 3 次，退避 1s/2s/4s"。结果：
- 40 秒抖动窗口内，
/api/v1/deductions（创建扣款）接口收到 6,847 次重试请求，其中 217 次落到了已经执行成功但响应没回来的订单上——用户被扣了两次款，涉及 11 个企业客户、金额合计 4.7 万元； - 客服工单 63 条，财务对账花了 2 个工作日才把重复扣款全部定位出来；
- 更隐蔽的：抖动期间
/api/v1/orders（查询）接口的重试是安全的，所以监控大盘上"重试成功率 98.6%"一片祥和，没人意识到写接口在流血。
另一个更早的案例：我们给 SDK 加了"408/409 不重试"的规则，但有个下游代理（Nginx 1.24，proxy_next_upstream 默认 error timeout）在 5xx 时自己也会重试。客户端 1 次 + 代理 1 次 = 每个请求最多 2 次执行。站内有篇复盘讲得很透：Nginx 的故障判定是单侧的，它不知道上游是否真的处理失败，对非幂等 POST 来说它就变成了"重复执行引擎"（见引用文章）。重试是乘法，不是加法——这是所有事故里最反直觉的一点。
二、原理：为什么"能不能重试"取决于错误码的语义，而不是网络状态
HTTP 错误码在设计上就携带了"请求是否已被处理"的信息，但绝大多数 SDK 把它当成"网络故障的统一信号"来对待。拆开看，错误码其实分四类：
| 类别 | 典型码 | 语义 | 对写接口能否重试 | |---|---|---|---| | 确定未处理 | 400、401、403、404、422 | 请求被明确拒绝，未执行 | 不该重试（重试只会再失败一次，还刷爆告警） | | 明确限流 | 429 | 未执行，且服务端告诉你何时再来 | 该重试，但必须尊重 Retry-After，且要有预算上限 | | 结果未知 | 408、504、连接超时、读到一半断流 | 请求可能已执行、可能没执行 | 写接口默认不重试，除非接口有幂等键 | | 服务端故障 | 500、503 | 大概率未执行，但不保证 | 写接口不重试；读接口可带退避重试 |
关键机制在第三类。以 504 为例：网关等上游响应超时，但上游很可能正在处理甚至已经处理完了——它只是没在时限内把响应发回来。此时客户端发起同一个请求，对幂等接口（带 idempotency key）是"取回上次结果"，对非幂等接口就是"再执行一次"。
还有一个产品层面的机制：重试会改变接口的 SLO 口径。假设服务端承诺可用性 99.9%（月度错误率 0.1%），客户端加 3 次重试后，用户侧感知到的错误率变成 0.1%^4 ≈ 0.000001%——看起来完美，但代价是服务端承受的流量是名义流量的 1 + 0.1%×3 + …，而且这些重试流量全部发生在服务端最脆弱的时候（正在出错的时候）。重试不是免费的容错，它是把故障时段的流量放大 1.3 倍（按 0.1% 错误率、3 次重试算）。
三、具体做法：四问决策 + 白名单 + 预算公式
3.1 决策四问（写接口重试前必须全部为"是"）
- 幂等吗？ 接口有稳定的幂等键（业务唯一键 + 唯一索引，或 idempotency key），重试是"取回结果"而不是"再执行"？
- 同 body 可重放吗？ 同一个 key 换个 body 重放，服务端返回的是"上次结果"还是"409 冲突"？（这两种语义对用户的含义完全不同，必须先和产品确认）
- 重试次数会改变业务语义吗？ 比如"查询余额"重试 3 次都拿到旧值，用户会不会据此做错误决策？
- 全链路重试次数乘出来是多少？ 客户端 × 代理 × 服务间调用，总执行次数是否 ≤ 2？
3.2 错误码白名单（可直接抄的默认配置）
// sdk-retry-policy.json —— 读接口
{
"retryable": ["408", "429", "500", "502", "503", "504", "CONNECT_TIMEOUT", "READ_TIMEOUT"],
"max_attempts": 3,
"backoff": { "base_ms": 500, "factor": 2, "jitter": "full" },
"budget_pct_of_errors": 0.5,
"respect_retry_after": true
}
// sdk-retry-policy.json —— 写接口（无幂等键）
{
"retryable": ["429"],
"max_attempts": 1,
"backoff": { "base_ms": 1000, "jitter": "full" },
"budget_pct_of_errors": 0.2,
"respect_retry_after": true,
"note": "429 是唯一明确'未执行'且服务端主动要求稍后再来的码；其余一律上抛给调用方决策"
}
注意两个数字：写接口预算从 0.5% 收紧到 0.2%——因为写接口一次重试错误的代价是资损，读接口只是体验降级，风险不对称，预算就该不对称。
3.3 重试预算公式
重试预算 = 接口月度错误率目标 × 允许重试比例
例：查询接口月度错误率目标 0.1%
→ 每 10,000 个成功请求，最多允许 0.1% × 0.5 = 0.05% 的请求进入重试
→ 即每 2000 个请求最多 1 个触发重试
例：写接口（有幂等键）
→ 每 10,000 个成功请求，最多 0.1% × 0.2 = 0.02% 进入重试
→ 即每 5000 个请求最多 1 个触发重试
预算耗尽后，SDK 必须立即停止重试并把错误原样上抛，并在响应头带上 Retry-Budget-Exhausted: true 让调用方知道"不是网络问题，是策略拒绝"。
3.4 退避参数
- 基础 500ms（读）/ 1000ms（写），factor=2，必须 full jitter（
sleep = random(0, base × factor^attempt)），否则 N 个客户端会同步重试形成二次踩踏； - 单次请求总重试时长上限：读接口 3s、写接口 2s——超过就放弃，因为超时越长，"结果未知"的概率越高。
四、踩过的坑（反直觉清单）
- 408 不是安全重试的"安全码"。408 表示"请求超时未处理"，但很多网关实现里 408 和 504 是同一个代码路径（等上游超时），语义完全一样：可能已执行。我们最初把 408 放进白名单，后来发现一次 408 风暴里 30% 的请求实际已落库。
- 重试是乘法。客户端 3 次 × Nginx 1 次 = 6 次执行。全链路任何一层有自动重试，总次数都要重算，且要在 API 文档里只允许一层做重试。
- 监控大盘会骗你。重试把用户侧错误率从 0.1% 抹到 0.000001%，大盘一片绿，但服务端故障时段的流量被放大 1.3 倍——必须单独监控"重试率"和"重试后仍失败的次数"，这两条曲线才是重试策略真实健康的信号。
- 429 的 Retry-After 经常是错的。我们实测过一个网关，限流时返回
Retry-After: 0，SDK 如果照做就是 0 延迟立即重试，等于没有限流。防御：Retry-After < 500ms时按 500ms 处理。 - 重试策略要跟着接口走，不能跟着 SDK 走。同一个 SDK 里查询和扣款用同一套 retry 配置，这是所有事故的公共根因。策略必须按 endpoint 粒度配置，写进 SDK 的接口声明里，而不是全局一份。
五、结论与可复用清单
核心认知：重试策略 = 错误码语义 × 接口幂等性 × 预算。三者缺一，就是把"结果未知"当"确定失败"处理，对非幂等写接口就是资损引擎。
可直接落地的清单（按顺序执行）：
- 盘点所有写接口，标出哪些有幂等键、哪些没有——没有幂等键的写接口，SDK 重试白名单里只允许 429；
- 全链路（客户端 → 代理 → 服务间）画出重试次数，总执行次数 ≤ 2，只允许一层做重试，写进 API 文档；
- 按 3.2 的模板给读/写接口分别配置错误码白名单，jitter 用 full，总重试时长上限读 3s / 写 2s；
- 按 3.3 公式算出每个接口的重试预算，SDK 内置预算耗尽熔断，响应头带
Retry-Budget-Exhausted； - 监控三条独立曲线：重试率、重试后仍失败次数、429 占比——不要只看用户侧错误率大盘；
- 把"重试策略变更"纳入变更评审：它和改超时、改限流一样，是一次全链路流量模型变更，不是改一行配置。
一句话收尾：读接口的重试是体验问题，写接口的重试是资损问题——用同一个默认配置去处理这两类接口，等于用同一条安全带绑大人和婴儿。