速率限制
Stripe API 采用了许多针对入站流量突发的保护措施,以最大限度提高稳定性。快速且连续发送许多请求的用户可能会看到错误响应,显示为状态代码 429
。我们在 API 中有几个限制器,包括:
一个速率限制器,用于限制 API 在任何一秒内接收的请求数量。
对于大多数 API,实时模式下,Stripe 每秒最多允许 100 个读取操作和 100 个写入操作;在测试模式下,每秒允许 25 个操作。
对于 Files API,Stripe 每秒最多允许 20 次读取操作和 20 次写入操作,真实模式和测试模式均是如此。真实模式和测试模式的限制是独立的。
对于 Search API,Stripe 每秒最多允许 20 次读取操作,该限制适用于真实模式和测试模式中所有的搜索端点。真实模式和测试模式的限制是独立的。
一个并发限制器,限制任何给定时间内的活动的请求数量。相比于请求速率限制器,这种限制器的问题不太常见,但它更有可能导致大量占用资源的长时间请求。
将这些限制视为最大值,不要产生不必要的负载。关于如何处理 429 错误的建议,请参阅适度处理限制。如果突遇有速率限制的请求数量增加的情况,请联系支持。
我们可能会通过调低限值来防止滥用,或调高限值以启用高流量应用。要请求提高速率限制,请联系支持。如果您要求大幅提高,请提前 6 周联系我们。
常见原因及缓解措施
速率限制可能发生于多种情况下,但最常见的情况是:
- 运行大量密集的请求会导致速率限制。这通常发生在进行分析或迁移操作时。进行这类活动时,应该尝试在客户端控制请求速率(参见适度处理限制)。
- 发布许多长时间请求可触发限制。不同的请求所占用的 Stripe 服务器资源量各不相同,大量占用资源的请求往往需要的时间更长,并有可能导致并发限制器丢弃新的请求。资源需求差异很大,但是列表请求以及包含扩展的请求通常会占用更多资源,运行时间也更长。建议对 Stripe API 请求的持续时间进行分析,并观察超时情况,从而找出那些异常缓慢的请求。
- 像限时抢购这种收款量突增的情况就可能会造成速率限制。我们会尽量将我们的速率设置得足够高,以便绝大多数用户的合法付款流量永远不会受到速率限制,但是如果您担心即将开展的活动可能会使您超出上述限值,则请联系支持。
适度处理限制
让集成应用适度处理限制的一个基本方法是观察 429
码并建立重试机制。重试机制应遵循指数退避计划,以便在必要时减少请求量。我们还建议在退避时间表中加入一些随机性,避免产生惊群效应 (thundering herd)。
您只能在一个受限程度内优化单个请求,因此一个更复杂的方法是在全局级别控制到 Stripe 的流量,而且在检测到明显的速率限制时,应减慢速度。控制速率的一个常见方法是在客户端部署类似令牌桶速率限制算法的东西。几乎任何编程语言中都有可拿来即用的成熟令牌桶。
对象锁定超时
集成可能会遇到 HTTP 状态为 429
、错误代码为 lock_timeout
的错误,以及以下消息:
目前不能访问该对象,因为有另一个 API 请求或 Stripe 进程正在访问它。如果您只是偶尔看到该错误,请重试请求。如果您频繁看到该错误,并且正在同时对一个对象发出多个请求,请逐次发出请求或降低请求频率。
Stripe API 会在某些操作上锁定对象,以便并发工作负载不会干扰并产生不一致的结果。上述错误是因为一个请求试图获取的锁已经被保持在了其他地方,在无法及时获取后便发生了超时。
锁定超时 (Lock timeouts) 的原因与速率限制不同,但其缓解措施类似。与速率限制错误一样,建议按指数退避计划重试(请参见适度处理限制)。但与速率限制错误不同的是,Stripe 的客户端库内置的自动重试机制会重试锁定超时导致的 429
:
锁竞争 (Lock contention) 是由相关对象上的并发访问引起的。通过确保在多线程突然访问同一个对象时对其进行排队并按顺序运行,集成应用可以大大减少这种情况。对 API 的并发操作仍然可行,但要确保同时操作只针对唯一的对象。还有可能会看到与内部 Stripe 后台进程冲突导致的锁竞争,这种情况应该很少,但因为这超出了用户的控制能力,所以建议所有集成都能重试请求。
负载测试
在用户为重大销售活动做准备时,通常会对系统进行负载测试,其中就包括在测试模式下运行的 Stripe API。我们一般不鼓励这种做法,因为测试模式下的 API 限制较低,所以负载测试会冲击的限制在生产环境下根本不会遇到。测试模式也不能完美替代真实的 API 调用,而且极有可能造成误导。例如,在真实模式下创建收款时会向支付网关发送一个请求,然而在测试模式下模拟该请求会导致明显不同的延迟情况。
作为一种替代方案,我们建议构建的集成应用能够有一个可配置的系统来模仿 Stripe API 请求,然后启用它进行负载测试。从集成的角度来看,要获得真实的结果,应通过一段睡眠时间来模拟延迟,这个睡眠时间通过对真实模式下的实际 Stripe API 调用的持续时间进行采样来确定。
API 读取请求的分配
Stripe 允许访问其 API 读取 (GET) 请求,以促进与支付集成相关的合理查找活动。为最大限度地提高所有用户的服务质量,Stripe 根据交易计数为读取请求作如下分配:
- 对于一个账户,API 读取请求不应超过每笔交易 500 次请求的平均比率。 例如,如果一个账户在 30 天内处理了 100 笔交易,那么在同一时期内,其 API 读取请求不应超过 50000 个。
- 使用 Connect 时,平台及其 Connect 子账户具有不同的读取 API 权限:
- 每个 Connect 子账户都有自己的请求分配数量(每笔交易 500 个请求)。
- Connect 平台使用单独的分配方式来代其 Connect 子账户使用其 API 私钥或 OAuth 访问令牌发出读取请求。这种分配方式也是每笔交易 500 个请求,基于的是其 Connect 子账户的总交易数。
- 比率为 30 天滚动测量。
- 每个账户,无论交易数量多少,每月至少分配 1 万个读取请求。
- 在写入 API 请求方面没有分配限制。
上述分配限制不包含对以下 API 端点的调用:
要减少 API 请求量,请考虑使用 Stripe Data Pipeline,将 API 数据完全导出到本地数据库或提供程序。
筛选请求以限制分页调用
有些列表端点会返回结果的多个页面,并且可能需要多个请求来返回列表操作的完整 API 对象集。尽可能应用筛选器来缩小列表结果的范围。