レート制限

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

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

API の制限

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

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

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

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

レートリミッター

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

本番環境: 100 件の読み取り操作と 100 件の書き込み操作
テスト環境: 25 件の読み取り操作と 25 件の書き込み操作

一部のリソースのコールにはより厳しい制限が適用され、基本的な制限においても不利に作用します。これらの厳しい制限は、本番環境とテスト環境に別々に適用されます。

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

本番環境の Meter Events エンドポイントのコールは、別のレート制限の対象となり、基本的な制限にはカウントされません。上限は、Stripe アカウントごとに 1 秒あたり 1,000 件です。テスト環境では、Meter Events エンドポイントのコールは、基本的な制限に対してカウントされます。Connect プラットフォームでは、連結アカウントから Meter Events エンドポイントのコールも基本的な制限にカウントされます。

並行リミッター

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

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 が再試行されます。

ロックの競合は、関連オブジェクトへの並行アクセスが原因で発生します。組み込みでは、同じオブジェクトのミューテーションをキューに入れ、代わりに順次実行するようにすることで、ロックの競合を大幅に削減できます。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 データをローカルのデータベースまたはプロバイダーに完全にエクスポートすることをご検討ください。

リクエストをフィルター処理してページ分割されるコールを制限する

一部のリストエンドポイントからは、複数ページの結果が返されるため、1 つのリスト操作に対する一連の API オブジェクトをすべて返すには複数のリクエストが必要になる場合があります。可能な場合は、フィルターを適用してリスト結果を絞り込んでください。