レート制限

Stripe API は、入力トラフィックのバーストに対する多くの保護手段を使用して、安定性を最大化します。多くのリクエストをすばやく連続して送信すると、ステータスコード 429 のエラー応答が表示される場合があります。

API の制限

Stripe の API には、レートリミッターや並行リミッターなど、いくつかのリミッターがあります。

制限は最大値として扱い、不要な負荷を生成しないようにしてください。不正利用を防ぐため、上限を引き下げる場合があります。

429 エラーの処理に関するアドバイスについては、制限の適切な処理をご覧ください。レート制限がかかったリクエストの数が急増している場合は、Stripe サポートにお問い合わせください。

高トラフィックのアプリケーションを有効にするために、上限の引き上げをご希望の場合は、Stripe サポートにお問い合わせください。大幅な引き上げをリクエストする場合は、少なくとも 6 週間前までにお問い合わせください。

レートリミッター

基本的なレートリミッターは、1 秒あたりの API リクエスト数を次のように制限します。

• 本番環境:100 回
• サンドボックス:25 回

個々のリソースの呼び出しにはより厳しい制限が課せられ、グローバル制限に対してもカウントされます。API エンドポイントのデフォルトの制限は、1 秒あたり 25 リクエストです。使用量に基づいて、Stripe は特定のアカウントに対するレート制限を引き上げることがあります。

• Files API: 1 秒あたり 20 件の読み取り操作と 20 件の書き込み操作
• Search API: 1 秒あたり 20 件の読み取り操作

本番環境での Meter イベントエンドポイントへのコールには、個別のレート制限が適用され、基本制限にはカウントされません。制限は、Stripe アカウントごとに毎秒 1000 コールです。サンドボックスでは、Meter イベントエンドポイントへのコールは基本制限にカウントされます。Connect プラットフォームの場合、Meter イベントエンドポイントへの連結アカウントからのコールも基本制限にカウントされます。

レート制限されたリクエスト

レート制限されたリクエストは、超過したレート制限の値を持つ Stripe-Rate-Limited-Reason ヘッダーを返します。このヘッダーが持つ値は次のとおりです。

• global-concurrency:リクエストがグローバルの同時実行数上限を超えました。同時に送信するリクエストの数を減らすことで、このような事態は回避できます。
• global-rate:リクエストがグローバルのレート制限を超えました。リクエストを低レートで送信することで、このような事態は回避できます。
• endpoint-concurrency:この API エンドポイントに対するリクエストが同時実行数上限を超えました。このエンドポイントに同時に送信するリクエストの数を減らすことで、このような事態は回避できます。
• endpoint-rate:この API エンドポイントに対するリクエストがレート制限を超えました。このエンドポイントへのリクエストを低レートで送信することで、このような事態は回避できます。
• resource-specific:特定の API リソースのレート制限に達しました。詳細については、そのリソースのドキュメントを参照してください。

リクエストがこれらのヘッダーなしで 429 ステータスコードを返しても、それらはレート制限に起因するものではありません (ロックタイムアウトなど)。

並行リミッター

並行リミッターは、同時に発生するアクティブなリクエストの数を制限します。このリミッターの問題は、レートリミッターほど一般的ではありませんが、リソースを大量に消費する、存続期間の長いリクエストが発生する可能性が高くなります。

Meter Events エンドポイントのコールは、メーターごとに顧客 1 人あたり並行して 1 件に制限されます。

一般的な原因と対策

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

• 短い間隔で大量のリクエストを実行すると、レート制限にが発生することがあります。多くの場合これは分析や移行の操作の一環で発生します。これらのアクティビティを実行する際には、クライアント側でリクエストのレートを制御するようにしてください (制限の適切な処理をご覧ください)。
• 存続時間が長い多量のリクエストを行うと制限がトリガーされることがあります。使用される Stripe のサーバリソースの使用量は、リクエストによって異なります。リソースを集中的に使用するリクエストは時間がかかる傾向があり、並行リミッタによって新しいリクエストが遮断されるリスクがあります。リソース要件は多岐にわたりますが、リストリクエストや拡張を含むリクエストは一般に多くのリソースを消費し、実行に時間がかかります。Stripe API リクエストの所要時間をプロファイリングし、タイムアウトを監視して、予想以上に遅いリクエストを判別することをお勧めします。
• フラッシュセールのように支払い高が急増した場合は、レート制限が発生することがあります。Stripe は、正規の支払いトラフィックが制限を超えることがないようにレートを十分に高く設定していますが、今後のイベントで上記のように制限を超える可能性があると思われる場合は、Stripe サポートまでお問い合わせください。

制限の適切な処理

組み込みが制限を適切に処理するための基本的な手法は、429 ステータスコードを監視し、再試行メカニズムを組み込むことです。再試行メカニズムは、必要に応じてリクエスト量を減らすために指数バックオフスケジュールに従う必要があります。また、Thundering Herd の影響を回避するために、バックオフスケジュールにランダム性を組み込むことをお勧めします。

個々のリクエストは限られた程度にしか最適化できないため、さらに高度なアプローチをとるには、Stripe へのトラフィックをグローバルレベルで制御し、大幅なレート制限が検出された場合はそれを抑制します。レートを制御する一般的な手法は、クライアント側でトークンバケットレート制限アルゴリズムのようなものを実装することです。既製の完成したトークンバケットは、ほとんどすべてのプログラミング言語で実装可能です。

オブジェクトロックのタイムアウト

システムでは、HTTP ステータス 429、コード lock_timeout、および次のメッセージのエラーが発生する場合があります。

別の API リクエストまたは Stripe プロセスがアクセスしているため、このオブジェクトに現在アクセスできません。このエラーが断続的に表示される場合は、リクエストを再試行してください。このエラーが頻繁に発生し、1 つのオブジェクトに対して複数の同時リクエストを行っている場合は、リクエストを順次処理するか、より低速で行ってください。

並行ワークロードが干渉したり、一貫性のない結果を生成したりしないように、Stripe API は一部の操作でオブジェクトをロックします。上記のエラーは、リクエストがどこかですでに保持されているロックを取得しようとして、そのロックを時間内に取得できずタイムアウトしたために発生したものです。

ロックタイムアウトの原因はレート制限とは異なりますが、対策は似ています。レート制限エラーと同様に、指数バックオフスケジュールで再試行することをお勧めします (制限の適切な処理を参照)。ただし、レート制限エラーとは異なり、Stripe の SDK に組み込まれている自動再試行メカニズムでは、ロックタイムアウトによって発生した 429 が再試行されます。

Stripe.max_network_retries = 2

ロックの競合は、関連オブジェクトへの並行アクセスが原因で発生します。組み込みでは、同じオブジェクトのミューテーションをキューに入れ、代わりに順次実行するようにすることで、ロックの競合を大幅に削減できます。API に対する並行操作は今までどおり問題ありませんが、同時操作は一意のオブジェクトでのみ動作することを確認してください。内部の Stripe バックグラウンドプロセスとの競合が原因でロックの競合が発生する可能性もあります。これはまれですが、ユーザが制御できないので、すべての組み込みでリクエストを再試行できるようにすることをお勧めします。

負荷テスト

ユーザーは、システムの負荷テストを行い、その一環として Stripe API を実行して、大規模な販売イベントに備えるのが一般的です。サンドボックスでは API の制限が低いため、この負荷テストは、本番環境では到達しない制限に達する可能性が高いため、通常この方法はお勧めしません。また、サンドボックスは本番環境の API コールの完全な代役ではなく、やや誤解を招く可能性があります。たとえば、本番環境で支払いを作成すると、ペイメントゲートウェイにリクエストが送信され、そのリクエストはサンドボックスでモックされるため、レイテンシープロファイルが大幅に異なります。

別の方法として、Stripe API へのリクエストをモックアウトするための設定可能なシステムを持つようにシステムを構築し、それを負荷テストで有効にできるようにすることをお勧めします。現実的な結果を得るために、構築システムの観点から、しばらくスリープすることで待ち時間をシミュレーションする必要があります。この時間は、実際の本番環境の Stripe API コールの時間をサンプリングして判断します。

API 読み取りリクエストの割り当て

Stripe では、決済システムに関連する合理的な検索アクティビティーを円滑にするために、その読み取り (GET) API リクエストにアクセスできるようにしています。すべてのユーザーに対して最大限のサービスを提供するために、Stripe では、取引数に基づいて読み取りリクエストを次のように割り当てています。

• 1 アカウントの読み取り API リクエストが、取引ごとに 500 リクエストという平均比率を超えないこと。たとえば、アカウントが 30 日間に 100 件の取引を処理する場合、その同じ期間に読み取り API リクエストが 50,000 件を超えないようにする必要があります。
• Connect を使用するときは、次のようにプラットフォームとその連結アカウントの読み取り API の割り当てが異なります。
  • 連結アカウントには、それぞれが開始するリクエストに対して、個別の割り当てがあります (取引ごとに 500 リクエスト)。
  • Connect プラットフォームは、連結アカウントに代わって連結アカウントのシークレット API キーまたは OAuth アクセストークンを使用して読み取りリクエストを行うために別個の割り当てを使用します。この割り当ても、連結アカウント全体の集計取引数に基づいて、取引ごとに 500 リクエストです。
• 比率は 30 日ごとに測定されます。
• すべてのアカウントに、取引数に関係なく月ごとに最低 10,000 件の読み取りリクエストが割り当てられます。
• 書き込み API リクエストには、割り当て制限はありません。

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

• データプロダクト
• レポート作成プロダクト
• 税務処理プロダクト

API リクエスト量を削減するために、Stripe Data Pipeline を使用して API データをローカルのデータベースまたはプロバイダーに完全にエクスポートすることをご検討ください。