速率限制
了解 API 速率限制及其使用方法。
Stripe API 针对突发的传入流量采取多项保护措施，以帮助最大限度地提高其稳定性。如果您连续快速发送许多请求，则可能会看到状态代码为 429 的错误响应。
API 限制器
我们的 API 中有几个限制器，包括速率限制器和并发限制器。
将限制视为最大值，不要生成不必要的负荷。为防止滥用，我们可能会调低限制。
有关处理 429 错误的建议，请参阅适度处理限制。如果您发现速率受限的请求的数量突然上升，请联系 Stripe 支持。
您可以通过联系 Stripe 支持来请求提高限制，以启用高流量应用。如果您要求大幅提高，请至少提前 6 周联系我们。
速率限制器
基本速率限制器限制的是每秒 API 请求的数量，具体如下：
- 真实模式：100 操作
- 沙盒:25 操作
对单个资源的调用有更严格的限制，同时也会计入全局限制。API 端点的默认限制为每秒 25 个请求。Stripe 可能会根据使用情况提高特定账户的速率限制。
在真实模式下对量表事件端点的调用有独立的限制，不计入基本限制。限制为每个 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 请求的持续时间进行分析，并观察超时情况，从而找出那些异常缓慢的请求。
- 像限时抢购这种收款额突增的情况就可能会造成速率限制。我们会尽量将我们的速率设置得足够高，以便合法付款流量永远不会超过限制，但是如果您担心即将开展的活动可能会使您超出上述限值，则请联系支持。
适度处理限制
让集成适度处理限制的一个基本方法是观察 429 码并建立重试机制。重试机制应遵循指数退避计划，以便在必要时减少请求量。我们还建议在退避时间表中加入一些随机性，避免产生惊群效应 (thundering herd)。
您只能在一个受限程度内优化单个请求，因此一个更复杂的方法是在全局级别控制到 Stripe 的流量，而且在检测到明显的速率限制时，应减慢速度。控制速率的一个常见方法是在客户端部署类似令牌桶速率限制算法的东西。几乎任何编程语言中都有可拿来即用的成熟令牌桶。
对象锁定超时
集成可能会遇到 HTTP 状态为 429、错误代码为 lock_ 的错误，以及以下消息：
目前不能访问该对象，因为有另一个 API 请求或 Stripe 进程正在访问它。如果您只是偶尔看到该错误，请重试请求。如果您频繁看到该错误，并且正在同时对一个对象发出多个请求，请逐次发出请求或降低请求频率。
Stripe API 会在某些操作上锁定对象，以便并发工作负载不会干扰并产生不一致的结果。上述错误是因为一个请求试图获取的锁已经被保持在了其他地方，在无法及时获取后便发生了超时。
锁定超时的原因与速率限制的原因不同，但缓解措施是类似的。与速率限制错误一样，我们建议按照指数退避计划重试（请参见适度处理限制）。但与速率限制不同的是，Stripe 的 SDKs 中内置的自动重试机制可以重试由锁定超时引起的 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 对象集。条件允许时应用筛选器，以缩小结果范围。