# 当响应消失时，Stripe 会记住您的请求

Published: 2026-10-11

服务器完成操作后，超时可能会使结账处于不确定状态。本篇“Under the Hood”解释器使用 Stripe API v1 中有文档记录的幂等性契约来展示稳定的操作键、已保存响应的重放、参数和并发限制、保留期限以及结果协调。

Canonical: https://thedailydiff.dev/zh-CN/video/idempotency-retries/

## 本视频涵盖的内容

- 幂等性关注重复操作的预期效果。Stripe API v1 增加了有文档记录的已保存响应重放契约。
- 同一逻辑操作的重试使用相同的键和参数。在不同的 SDK 调用或应用程序重启之间保留操作键；真正的新操作需要自己的键。
- 端点执行开始后，Stripe API v1 会保存第一个请求的状态和正文，包括 500 错误，并在重试时返回该已保存的响应。
- 更改参数但使用相同的键会产生不匹配。验证失败和并发执行冲突不会为该尝试保存幂等结果，可以重试。
- Stripe 至少保留 API v1 键 24 小时，之后可能会对其进行清除。将未解决的网络重试限制在前 24 小时内，然后停止并在重复操作之前进行协调。
- 连接恢复后，缓存的 500 错误可能会持续重放。原始操作可能产生副作用；使用相关对象、管理平台请求和 Webhook 来确定其结果。
- API v2 使用不同的重放语义。键不能为电子邮件、库存和每个本地数据库操作建立通用的精确一次交付。

## 章节

- 0:00 超时取消了您的付款吗？
- 0:21 幂等性键标识了什么？
- 0:43 相同的键如何使重试安全？
- 1:07 Stripe 到底保存了什么？
- 1:28 请求更改时会发生什么？
- 1:56 记住的结果重试多久是安全的？
- 2:19 为什么记住的错误会一直出现？
- 2:39 我会用这个契约发布重试按钮吗？

## 翻译的文字记录

译自英文原版旁白。可用音频和字幕由 YouTube 控制。

### 超时取消了您的付款吗？

0:00 您认为超时意味着您的付款失败了。 服务器可能在回复消失时完成操作， 让您的结账自信地显示一片空白。 为什么重试会再次收费？ Stripe 如何记住一次尝试？ 您何时应该停止重试？ 并且请记住一个讨厌的细节。 记住的错误可能比网络问题持续更长时间。

0:17 我们稍后会回来讨论这个问题。 这是 The Daily Diff，幕后揭秘。

### 幂等性键标识了什么？

0:21 幂等性意味着重复操作与执行一次操作具有相同的预期效果。 幂等性键标记一个逻辑动作。 Stripe 的 API 版本一在重试时识别该标签并重放已保存的响应。 想象一下购买咖啡。 Stripe 完成您的付款请求，但在返回时响应丢失了。 客户看到一个加载图标。 他们的银行可能有更令人兴奋的解释。 不受保护的创建请求可能会重复副作用。

### 相同的键如何使重试安全？

0:45 在第一次尝试之前附加一个唯一的键，并保留它以供重试。 如果您的应用程序重新启动，请在您的记录中与操作一起保留该键。 对于 Stripe 的版本一 API，一旦端点执行开始， 第一个请求的状态和正文都会被保存。 再次发送相同的键和参数，Stripe 会返回保存的响应。 咖啡还在原处，而收据再次传输。

### Stripe 到底保存了什么？

1:07 这是 Stripe 的实际措辞。 使用相同的键重试会返回保存的响应， 包括 500 错误。 文档比您乐观命名的重试帮助程序做得更多。 客户再次点击。 您的应用程序决定是恢复待处理的购买还是开始新的购买。 真正的新咖啡会获得一个新的键。 每次网络重试都使用一个新的键会破坏保护。

1:27 相同键但不同参数会触发不匹配。

### 请求更改时会发生什么？

1:30 如果参数验证失败，或者具有该键的另一个请求仍在执行中， Stripe 不会为该尝试保存幂等结果。 这些请求可以重试。 并发请求会产生冲突。 这些是版本一的规则。 版本二的行为有所不同。 一个请求头不能保证您的系统中的电子邮件、库存和数据库的精确一次交付。 电子邮件、库存和您的数据库都需要故障处理。

1:52 该键在其文档范围内存保护操作。 Stripe 至少保留版本一的键 24 小时，之后可能会对其进行清除。

### 记住的结果重试多久是安全的？

1:59 清除后的键可以执行新请求。 在第一天内保持未解决的重试。 超过此期限，请停止并协调原始结果。 使用指数退避和抖动来给服务器喘息的空间。 否则重试会在一家着火的咖啡店外排队。 Stripe 的库处理重试，但请检查您的库的默认设置。 那个顽固的错误就是陷阱。

### 为什么记住的错误会一直出现？

2:20 连接恢复后，缓存的 500 响应会一直重放。 原始操作可能已产生副作用。 使用对象、管理平台和 Webhook 来解决其结果。 新的键可以重复该操作。 如果您宁愿阅读而不是听我说，diff 每天早上免费发送到您的收件箱， 网址是 thedailyiff.dev，链接如下。

### 我会用这个契约发布重试按钮吗？

2:39 结论，幕后揭秘。 SHIP IT。我会发布带有有界重试和协调的稳定键， 这样客户就可以喝到咖啡，而无需资助您的分布式系统教育。 这就是今天的 diff。 我是 Axrisi 的 Niko。 负责任地合并。

## 来源

- [Idempotent requests](https://docs.stripe.com/api/idempotent_requests) — Stripe Docs
- [Designing robust and predictable APIs with idempotency](https://stripe.com/blog/idempotency) — Stripe Engineering — Brandur Leach
- [Advanced error handling](https://docs.stripe.com/error-low-level) — Stripe Docs
- [HTTP Semantics — RFC 9110 §9.2.2 Idempotent Methods](https://www.rfc-editor.org/rfc/rfc9110.html) — IETF / RFC Editor