レート制限

Stripe は、API の安定性を最大化するために、着信トラフィックの急激な増加（バースト）に対する保護策を使用しています。多数のリクエストを連続して送信すると、429 のエラー応答を受け取る可能性があります。

API の制限

Stripe は、レート制限や同時実行制限など、いくつかの API リミッターを適用しています。制限は上限として扱い、不必要な負荷を避けてください。悪用を防ぐために、制限を引き下げることがあります。429 エラーの処理に関するアドバイスについては、制限の適切な処理をご覧ください。レート制限により拒否されたリクエストが増加している場合は、Stripe サポートにお問い合わせください。

トラフィックの多いアプリケーションについては、Stripe サポートを通じて制限の引き上げをリクエストしてください。大幅な引き上げをリクエストする場合は、少なくとも 6 週間前までに Advance Stripe サポートに問い合わせてください。

レートリミッター

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

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

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

• Payment Intents API: PaymentIntentあたり、1 時間につき 1,000 回の更新操作。
• Files API: 1 秒あたり 20 件の読み取り操作と 20 件の書き込み操作
• Search API: 1 秒あたり 20 回の読み取り操作。
• Subscriptions API:
  • 1 サブスクリプションあたり、1 分間に新規請求書 10 件。
  • 1 サブスクリプションあたり、1 日に新規請求書 20 件
  • 1 サブスクリプションあたり、1 時間に数量更新 200 件
• Payout API を作成: 加盟店あたりのリクエストは 1 秒あたり 15 件、同時実行リクエストは 30 件までです。
• 連結: プラットフォームは、サンドボックス環境では 1 秒あたり最大 5 アカウント、本番環境では 1 秒あたり最大 30 アカウントを作成できます。
• 発行: クレジットカード作成には、国とビジネスの業種に応じたレート制限があります。

本番環境での 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 ステータス コードを監視し、レート制限を処理するためのリトライ メカニズムを実装します。指数バックオフ スケジュールに従って必要に応じてリクエスト量を減らし、バックオフ スケジュールにランダム性を追加して、雷の群れ効果を回避します。

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

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

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

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

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

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

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 エンドポイントへのコールは、上記の割り当て制限対象から除外されます。

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

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