# 速率限制 了解 API 速率限制及其使用方法。 Stripe 采用速率限制机制以最大化 API 稳定性并防止滥用，因此请将限制值视为上限，避免产生不必要的负载。 若超出限制，您将收到 `429 Too Many Requests` HTTP 状态响应。有关处理 `429` 错误的建议，请参阅[妥善处理速率限制](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)。 ## 速率限制 通常而言，速率限制按每个 Stripe 账户每秒的 API 请求数计量。全局速率限制适用于每个账户的 API 总使用量，部分端点另有自身的额外限制。 | 资源 | 限制 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **全局 API 速率限制** | - *真实模式* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments)：每秒 100 次请求 - *沙盒* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes)：每秒 25 次请求 | | 单独 API 端点（除非另有说明） | 每秒 25 次请求 | | [Payment Intents API](https://docs.stripe.com/api/payment_intents.md) | 每个 PaymentIntent 对象每小时 1000 次更新请求 | | [订阅 API](https://docs.stripe.com/api/subscriptions.md) | - 每分钟每个订阅 10 张新发票 - 每天每个订阅 20 张新发票 - 每小时每个订阅 200 次数量更新 | | [文件 API](https://docs.stripe.com/api/files.md) | - 每秒 20 次读取请求 - 每秒 20 次写入请求 | | [Payouts API](https://docs.stripe.com/api/payouts.md) | - 每秒 15 次[创建](https://docs.stripe.com/api/payouts/create.md)请求 - 单商家 30 次[并发请求](https://docs.stripe.com/rate-limits.md#concurrency-limits) | | *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients) 账户，包括两类： - [Accounts v2](https://docs.stripe.com/api/v2/core/accounts.md) - [Accounts v1](https://docs.stripe.com/api/accounts.md) | - *真实模式* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments)：每秒创建 30 个账户 - *沙盒* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes)：每秒创建 5 个账户 | | [搜索 API](https://docs.stripe.com/search.md#rate-limits)1 | 每秒 20 次读取请求 | | [Issuing](https://docs.stripe.com/issuing.md) | 创建银行卡的限制取决于发卡账户所在国家/地区和行业。 | 考虑使用 [Sigma](https://docs.stripe.com/data/sigma.md) 或 [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) 作为数据密集型分析任务的更有效选项。 ## 并发限制 并发限制用于限制同时处于活跃状态的请求数量，与速率限制相互独立。速率限制通常每秒重置一次，而并发限制统计任意时刻正在处理的请求数。触发并发限制的情况不如速率限制错误常见，通常表明存在长时间运行或资源密集型的 API 请求，例如列表请求或包含[扩展](https://docs.stripe.com/expand.md)的请求。 ## 受速率限制的响应 受速率限制的请求返回一个 `429 Too Many Requests` HTTP 状态代码，并包含一个解释为什么限制了该请求速率的 `Stripe-Rate-Limited-Reason` 标头。该标头可能的值为： | 标头值 | 含义 | | ------ | ---------------------------------------------------- | | `全局速率` | 您的请求已超出全局速率限制。您可通过降低请求发送速率来避免此情况。 | | `端点速率` | 您对该特定 API 端点的请求已超出速率限制。您可通过降低向该接口发送请求的速率来避免此情况。 | | `全局并发` | 您的请求已超出全局并发限制。您可通过减少同时发送的请求数量来避免此情况。 | | `端点并发` | 您对此特定 API 端点的请求超出了并发限制。您可以通过向此特定端点发送较少并发请求来防止出现这种情况。 | | `资源特定` | 您已触发与特定 API 资源相关的速率限制。如需了解更多信息，请参阅该资源的文档。 | 若请求返回 `429` 状态码但未包含上述标头，则并非速率限制导致。该情况可能是[锁超时](https://docs.stripe.com/rate-limits.md#object-lock-timeouts)所致。 ## 常见原因与缓解措施 速率限制可能发生于多种情况下，但最常见的情况是： - 运行**大量密集的请求**会导致速率限制。这通常发生在进行分析或迁移操作时。进行这类活动时，应该尝试在客户端控制请求速率（参见[适度处理限制](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)）。 - 收款量突然增加（例如**闪购**）可能会导致速率限制。我们尽量将速率设定得足够高，确保合法的支付流量不会超出限制，但如果您担心即将到来的活动可能超出上述限制，请[联系 Stripe 支持](https://support.stripe.com/)。 - 发出大量长时间运行的请求可能触发并发限制。不同请求占用的 Stripe 服务器资源量各不相同，资源密集型请求耗时更长，可能导致并发限制器拒绝新请求。资源需求差异很大，但列表请求和包含[扩展](https://docs.stripe.com/expand.md)的请求通常占用更多资源且运行时间更长。我们建议分析 Stripe API 请求的耗时并关注超时情况，以识别异常缓慢的请求。 ## 处理限制 注意 `429` 状态码并实施重试机制以应对速率限制。必要时，采用指数退避策略以降低请求量，并在退避计划中加入随机性，以避免出现[惊群效应](https://en.wikipedia.org/wiki/Thundering_herd_problem)。 更高级的方案是在全局层面控制发往 Stripe 的流量，并在检测到严重速率限制时降低流量。控制 API 使用量的一种常用方法是在客户端实现[令牌桶速率限制算法](https://en.wikipedia.org/wiki/Token_bucket)。大多数编程语言都有对应的令牌桶实现或库。 ## 对象锁定超时 集成可能会遇到 HTTP 状态为 `429`、错误代码为 `lock_timeout` 的错误，以及以下消息： > 该对象当前无法访问，因为另一个 API 请求或 Stripe 进程正在访问它。若您只是偶尔遇到此错误，请重试请求。若您频繁遇到此错误且正在对单个对象发起多个并发请求，请改为串行发送请求或降低请求速率。 Stripe API 会在部分操作中锁定对象，以防止并发任务相互干扰并产生不一致的结果。上述错误是由以下原因导致的：某请求尝试获取一把已在其他地方被占用的锁，且在超时时间内未能及时获取该锁，最终触发错误。Stripe 不会处理这些失败的请求，这意味着它们不会被分配[请求 ID](https://docs.stripe.com/api/request_ids.md)。 锁定超时的原因与速率限制的原因不同，但缓解措施是类似的。与速率限制错误一样，我们建议按照指数退避计划重试（请参见[适度处理限制](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)）。但与速率限制不同的是，Stripe 的 [SDKs](https://docs.stripe.com/sdks.md) 中内置的自动重试机制可以重试由锁定超时引起的 `429`： #### Ruby ```ruby Stripe.max_network_retries = 2 ``` 锁争用由对关联对象的并发访问引发。集成可通过确保同一对象的变更操作排队并按顺序执行，大幅减少此类问题。针对 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 端点的调用： - [数据产品](https://docs.stripe.com/data.md) - [报告产品](https://docs.stripe.com/stripe-reports.md) - [税务产品](https://docs.stripe.com/tax.md) 如需减少您的 API 请求量，请考虑使用 [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) 将 API 数据完整导出到您的本地数据库或服务商。 > #### 筛选请求以限制分页调用 > > 有些列表端点会返回结果的[多个页面](https://docs.stripe.com/api/pagination.md)，并且可能需要多个请求来返回列表操作的完整 API 对象集。条件允许时应用筛选器，以缩小结果范围。