速率限制
了解 API 速率限制及其使用方法。
我们采用防护措施来应对突发的入站流量,以最大程度保障 API 的稳定性。如果您在短时间内连续发送大量请求,可能会收到 429 错误响应。
API 限制器
我们采用了多种 API 限流器,包括速率限制器和并发限制器。请将这些限制视为上限,避免产生不必要的负载。为防止滥用,我们可能会降低您的限制额度。有关如何处理 429 错误的建议,请参阅优雅地处理限制。如果您发现速率限制请求增加,请联系 Stripe 支持。
如需为高流量应用提升限制额度,请通过 Stripe 支持提出请求。如需大幅提升限额,请至少提前 6 周联系 Stripe 支持。
速率限制器
基本速率限制器限制的是每秒 API 请求的数量,具体如下:
- 真实模式:100 操作
- 沙盒: 25 次操作
对单个资源的调用有更严格的限制,同时也会计入全局限制。API 端点的默认限制为每秒 25 个请求。Stripe 可能会根据使用情况提高特定账户的速率限制。
- Payment Intents API:每个 PaymentIntent 每小时执行 1000 次更新操作。
- Files API:每秒 20 次读取操作和 20 次写入操作。
- Search API:每秒 20 次读取操作。
- 订阅 API:
- 每个订阅每分钟 10 张新账单。
- 每个订阅每天 20 张新账单。
- 每个订阅每小时 200 次数量更新。
- 创建 Payout API:每秒 15 次请求,每个商家 30 次并发请求。
- Connect:平台在沙盒中每秒最多可创建 5 个账户,在真实模式中每秒创建 30 个账户。
- Issuing:制卡有速率限制,取决于国家/地区和业务行业。
在真实模式下对量表事件端点的调用有独立的限制,不计入基本限制。限制为每个 Stripe 账户每秒 1000 次调用。在沙盒环境下,对 Meter 事件端点的调用会计入基本限制。对于 Connect 平台,Connect 子账户上的量表事件端点调用也会计入基本限制。
速率限制请求
有速率限制的请求返回 Stripe-Rate-Limited-Reason 头,它的值指示请求超过了哪个速率限制。该标头的可能值为:
global-concurrency:您的请求已超过全局并发限制。您可以通过减少同时发送的请求来防止这种情况的发生。global-rate:您的请求已超过全局速率限制。您可以通过降低发送请求的速率来防止这种情况。endpoint-concurrency:您向此特定 API 端点发出的请求已超出并发限制。您可以通过减少向此特定端点同时发送的请求来防止这种情况。endpoint-rate:您向该特定 API 端点发出的请求已超过速率限制。您可以通过以较低的速率向此端点发送请求来防止这种情况。resource-specific:您达到了与特定 API 资源相关的速率限制。有关详细信息,请参阅该资源的文档。
如果某个请求返回一个没有这些标头的 429 状态码,则它不是速率限制器的结果(例如,可能是锁定超时)。
并发限制器
并发限制器限制的是并发活动请求的数量。此限制器的问题不如速率限制器常见,但它们可能表明存在大量占用资源的、长生命周期的请求。
对 Meter 事件端点 的调用仅限于每个客户每个量表一次并发调用。
常见原因与缓解措施
速率限制可能发生于多种情况下,但最常见的情况是:
运行大量密集的请求会导致速率限制。这通常发生在进行分析或迁移操作时。进行这类活动时,应该尝试在客户端控制请求速率(参见适度处理限制)。
发出大量长期请求可能会触发限制。不同的请求所占用的 Stripe 服务器资源量各不相同,大量占用资源的请求往往需要的时间更长,并有可能导致并发限制器丢弃新的请求。资源需求差异很大,但是列表请求以及包含扩展的请求通常会占用更多资源,运行时间也更长。建议对 Stripe API 请求的持续时间进行分析,并观察超时情况,从而找出那些异常缓慢的请求。
收款量突然增加(例如闪购)可能会导致速率限制。我们尽量将速率设定得足够高,确保合法的支付流量不会超出限制,但如果您担心即将到来的活动可能超出上述限制,请联系 Stripe 支持。
处理限制
注意 429 状态码并实施重试机制以应对速率限制。必要时,采用指数退避策略以降低请求量,并在退避计划中加入随机性,以避免出现惊群效应。
您只能在一个受限程度内优化单个请求,因此一个更复杂的方法是在全局级别控制到 Stripe 的流量,而且在检测到明显的速率限制时,应减慢速度。控制速率的一个常见方法是在客户端部署类似令牌桶速率限制算法的东西。几乎任何编程语言中都有可拿来即用的成熟令牌桶。
对象锁定超时
集成可能会遇到 HTTP 状态为 429、错误代码为 lock_ 的错误,以及以下消息:
目前不能访问该对象,因为有另一个 API 请求或 Stripe 进程正在访问它。如果您只是偶尔看到该错误,请重试请求。如果您频繁看到该错误,并且正在同时对一个对象发出多个请求,请逐次发出请求或降低请求频率。
Stripe API 会在部分操作中锁定对象,以防止并发任务相互干扰并产生不一致的结果。上述错误是由以下原因导致的:某请求尝试获取一把已在其他地方被占用的锁,且在超时时间内未能及时获取该锁,最终触发错误。Stripe 不会处理这些失败的请求,这意味着它们不会被分配请求 ID。
锁定超时的原因与速率限制的原因不同,但缓解措施是类似的。与速率限制错误一样,我们建议按照指数退避计划重试(请参见适度处理限制)。但与速率限制不同的是,Stripe 的 SDKs 中内置的自动重试机制可以重试由锁定超时引起的 429:
锁争用由对关联对象的并发访问引发。集成可通过确保同一对象的变更操作排队并按顺序执行,大幅减少此类问题。针对 API 的并发操作本身是允许的,但应尝试确保同时执行的操作仅作用于唯一对象。此外,锁争用也可能由 Stripe 内部后台进程的冲突导致,此类情况虽属罕见,但由于超出用户控制范围,我们建议所有集成均能够重试请求。
负载测试
在用户为重大销售活动做准备时,通常会对系统进行负载测试,其中就包括在沙盒环境中运行的 Stripe API。我们一般不鼓励这种做法,因为沙盒环境下的 API 限制较低,所以负载测试会冲击的限制在生产环境下根本不会遇到。沙盒环境也不能完美替代真实的 API 调用,而且极有可能造成误导。例如,在真实模式下创建收款时会向支付网关发送一个请求,然而在沙盒环境下模拟该请求会导致明显不同的延迟情况。
作为一种替代方案,我们建议构建的集成能够有一个可配置的系统来模仿 Stripe API 请求,然后启用它进行负载测试。从集成的角度来看,要获得真实的结果,应通过一段睡眠时间来模拟延迟,此睡眠时间通过对真实模式下的实际 Stripe API 调用的持续时间进行采样来确定。
API 读取请求分配
Stripe 允许访问其 API 读取 (GET) 请求,以促进与支付集成相关的合理查找活动。为最大限度地提高所有用户的服务质量,Stripe 根据交易计数为读取请求作如下分配:
您账户的读取 API 请求平均每笔交易不得超过 500 次。例如,如果您在 30 天内处理了 100 笔交易,则在此期间读取 API 请求不得超过 50,000 次。
使用 Connect 时,平台及其 Connect 子账户具有不同的读取 API 权限:
- 每个 Connect 子账户都有自己的请求分配数量(每笔交易 500 个请求)。
- Connect 平台使用单独的分配方式来代其 Connect 子账户使用其 API 私钥或 OAuth 访问令牌发出读取请求。这种分配方式也是每笔交易 500 个请求,基于的是其 Connect 子账户的总交易数。
比率按滚动 30 天周期(最近 30 天)计算。
每个账户,无论交易数量多少,每月至少分配 1 万个读取请求。
在写入 API 请求方面没有分配限制。
上述分配限制不包含对以下 API 端点的调用:
要减少 API 请求量,请考虑使用 Stripe Data Pipeline,将 API 数据完全导出到本地数据库或提供程序。
筛选请求以限制分页调用
有些列表端点会返回结果的多个页面,并且可能需要多个请求来返回列表操作的完整 API 对象集。条件允许时应用筛选器,以缩小结果范围。