# レート制限

API レート制限と使用方法について説明します。

Stripe では API の安定性を最大化し、不正利用を防止するためにレート制限を使用しています。そのため、制限を最大値として扱い、不必要な負荷を避けてください。

制限を超えると、`429 Too Many Requests` HTTP ステータスレスポンスを受け取ります。`429` エラーの処理に関するアドバイスについては、[制限のグレースフルな処理](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)をご覧ください。

## レート制限

通常、レート制限は、Stripe アカウントごとの 1 秒あたりの API リクエスト数で測定されます。グローバルなレート制限は、アカウントごとの合計 API 使用量に適用されますが、一部のエンドポイントには固有の追加の制限があります。

Stripe では、名前付きの各 API 操作を個別のエンドポイントとして扱います (例: `POST /v1/payment_intents` と `GET /v1/payment_intents/{id}` は別々のエンドポイントです)。異なる PaymentIntent ID に対する `GET /v1/payment_intents/{id}` へのリクエストは、同じエンドポイントの制限としてカウントされます。

| リソース | 制限 |
| --- | --- |
| **グローバルな API レート制限** | - *本番環境* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments): 1 秒あたり 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): 1 秒あたり 25 リクエスト |
| 個々の API エンドポイント (特に明記されていない場合) | 1 秒あたり 25 リクエスト |
| [Payment Intents API](https://docs.stripe.com/api/payment_intents.md) | 1 時間あたり PaymentIntent オブジェクトにつき 1,000 件の更新リクエスト |
| [Subscriptions API](https://docs.stripe.com/api/subscriptions.md) | - 新規請求書10件/分 (1サブスクリプション)
- 新規請求書20件/日 (1サブスクリプション)
- 数量更新200件/時間 (1サブスクリプション) |
| [Files API](https://docs.stripe.com/api/files.md) | - 1 秒あたり 20 件の読み取りリクエスト
- 1 秒あたり 20 件の書き込みリクエスト |
| [Payouts API](https://docs.stripe.com/api/payouts.md) | - 1 秒あたり 15 件の [create](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): 1 秒あたり 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): 1 秒あたり 5 個のアカウントの作成 |
| [Search API](https://docs.stripe.com/search.md#rate-limits)1 | 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) をご検討ください。

## 同時実行制限

同時実行制限は、レート制限とは別に、同時にアクティブなリクエストの数を制限します。一般的に 1 秒後にリセットされるレート制限とは異なり、同時実行制限は、同時に進行中のリクエスト数をカウントします。同時実行制限に達することは、レート制限エラーよりもまれであり、通常はリストリクエストや[拡張](https://docs.stripe.com/expand.md)を含むリクエストなど、長期間有効またはリソース集約型の API リクエストを示します。

## レート制限されたレスポンス

レート制限されたリクエストは `429 Too Many Requests` HTTP ステータスコードを返し、リクエストがレート制限された理由を説明する `Stripe-Rate-Limited-Reason` ヘッダーを含みます。このヘッダーに使用できる値は次のとおりです。

| ヘッダーの値 | 意味 |
| --- | --- |
| `global-rate` | 全体的なレート制限を超過しました。これはリクエストの送信レートを下げることで回避できます。 |
| `endpoint-rate` | この特定の API エンドポイントに対するリクエストのレート制限を超過しました。これは、このエンドポイントへのリクエストの送信レートを下げることで回避できます。 |
| `global-concurrency` | 全体的な同時実行制限を超過しました。これは、同時に送信するリクエストの数を減らすことで回避できます。 |
| `endpoint-concurrency` | この特定の API エンドポイントに対するリクエストの同時実行制限を超過しました。これは、この特定のエンドポイントに同時に送信するリクエストの数を減らすことで回避できます。 |
| `resource-specific` | サブスクリプションの更新エンドポイントや作成エンドポイントなど、このリソース内のいずれかのエンドポイントに対するリクエストに関連するレート制限を超過しました。これは、そのリソース全体のエンドポイントに対するリクエストの送信レートを下げることで回避できます。 |

リクエストがこれらのヘッダーなしで `429` ステータスコードを返した場合、それはレート制限の結果ではありません。[ロックタイムアウト](https://docs.stripe.com/rate-limits.md#object-lock-timeouts)である可能性があります。

## 一般的な原因と対策

レート制限はさまざまな状況で発生しますが、最も発生頻度が高いのは次のシナリオです。

- **短い間隔で大量のリクエスト**を実行すると、レート制限にが発生することがあります。多くの場合これは分析や移行の操作の一環で発生します。これらのアクティビティを実行する際には、クライアント側でリクエストのレートを制御するようにしてください ([制限の適切な処理](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)をご覧ください)。

- **フラッシュセール**のように支払い高が急増した場合は、レート制限が発生することがあります。Stripe は、正規の支払いトラフィックが制限を超えないよう、レートを十分に高く設定していますが、今後のイベントで上記のように制限を超える可能性があると思われる場合は、[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 のプロセスがアクセスしているため、このオブジェクトにアクセスできません。このエラーが断続的に発生する場合は、もう一度リクエストしてください。1 つのオブジェクトに対して複数のリクエストを同時に行っていて、この問題が頻繁に発生する場合は、リクエストを 1 つずつ順番に行うか、リクエストのペースを落としてください。

並行ワークロードが干渉して一貫性のない結果を生成しないように、Stripe API は一部の操作でオブジェクトをロックします。上記のエラーは、リクエストがどこかですでに保持されているロックを取得しようとして、そのロックを時間内に取得できずタイムアウトしたために発生したものです。Stripe はこれらの失敗したリクエストを処理しません。つまり、[request ID](https://docs.stripe.com/api/request_ids.md) が割り当てられていません。

ロックタイムアウトの原因はレート制限とは異なりますが、対策は似ています。レート制限エラーと同様に、指数バックオフスケジュールで再試行することをお勧めします ([制限の適切な処理](https://docs.stripe.com/rate-limits.md#handling-limiting-gracefully)を参照)。ただし、レート制限エラーとは異なり、Stripe の [SDK](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 では、決済システムに関連する合理的な検索アクティビティーを円滑にするために、その読み取り (GET) API リクエストにアクセスできるようにしています。すべてのユーザーに対して最大限のサービスを提供するために、Stripe では、取引数に基づいて読み取りリクエストを次のように割り当てています。

- アカウントの読み取り API リクエストは、取引ごとに平均 500 を超えることはできません。たとえば、30 日間に 100 件の取引を処理する場合、その期間中に読み取り API リクエスト数は、取引あたりの平均が 50,0000 を超えてはなりません。

- Connect を使用するときは、次のようにプラットフォームとその連結アカウントの読み取り API の割り当てが異なります。

  - 連結アカウントには、それぞれが開始するリクエストに対して、個別の割り当てがあります (取引ごとに 500 リクエスト)。
  - Connect プラットフォームは、連結アカウントに代わって連結アカウントのシークレット API キーまたは OAuth アクセストークンを使用して読み取りリクエストを行うために別個の割り当てを使用します。この割り当ても、連結アカウント全体の集計取引数に基づいて、取引ごとに 500 リクエストです。

- 比率は、ローリング 30 日間 (直近 30 日間) で計算されます。

- すべてのアカウントに、取引数に関係なく月ごとに最低 10,000 件の読み取りリクエストが割り当てられます。

- 書き込み API リクエストには、割り当て制限はありません。

次の API エンドポイントへのコールは、上記の割り当て制限対象から除外されます。

- [データプロダクト](https://docs.stripe.com/data.md)
- [レポート作成プロダクト](https://docs.stripe.com/stripe-reports.md)
- [税務処理プロダクト](https://docs.stripe.com/tax.md)

API リクエストの量を減らすには、ローカルデータベースまたはプロバイダーへの API データの完全なエクスポートに [Data Pipeline](https://docs.stripe.com/data/data-pipeline.md) を使用することをご検討ください。

> #### リクエストをフィルター処理してページ分割されるコールを制限する
> 
> 一部のリストエンドポイントからは、[複数ページ](https://docs.stripe.com/api/pagination.md)の結果が返されるため、1 つのリスト操作に対する一連の API オブジェクトをすべて返すには複数のリクエストが必要になる場合があります。可能な場合は、フィルターを適用してリスト結果を絞り込んでください。

## Request a limit increase

Request a limit increase for high-traffic applications through [Stripe Support](https://support.stripe.com/contact). If you request a large increase, contact Stripe Support at least 6 weeks in advance.