x-api-keyで、APIキーが送信されない場合はクライアントのIPアドレスです。各スコープでは、60秒のスライディングウィンドウを使用して独立したカウンターが維持されます。
識別子と適用除外
ミドルウェアは、次の順序でレート制限の識別子を選択します。x-api-keyヘッダー → キー単位のカウンター。X-Forwarded-Forの最初のホップ → IP単位のカウンター。REMOTE_ADDR→ IP単位のカウンター。
- 内部用の
DIDIT_WEBAPP_API_KEY(Didit コンソールのみが使用)。 IsValidSession権限で保護されたエンドポイント(埋め込み/SDKのセッショントラフィック)。GET /system/healthcheck(このスタックより前にHealthMiddlewareが処理)。- プロバイダーのWebhook: Stripe、AMLスクリーニング、顔認証のコールバック、KYCリストの変更。
グローバル制限
認証済みのリクエストはすべて、HTTPメソッドごとに汎用スコープにも振り分けられます。そのため、新しいルートにも妥当なデフォルト値が自動的に適用されます。
エンドポイント固有の制限(次のセクション)は、グローバル制限に加えて適用されます。最初にカウンターの上限を超えたスコープが
429を返します。
エンドポイント固有の制限
ミドルウェアは、影響の大きいルートに対してより厳しいスコープを定義しています。GET /v3/session/<id>/decision/はSessionV3RetrieveViewが処理しており、session-decisionスコープには含まれません。このエンドポイントにはgeneric-getの上限である600/minのみが適用されます。100/minの判定スロットルは、v1とv2の判定パスに適用されます。429レスポンスの形式
いずれかのスコープの上限を超えると、次のボディとヘッダーを含むHTTP429が返されます。
X-RateLimit-*ヘッダーは429レスポンスでのみ出力されます。現時点では、成功したレスポンスには含まれません。次の試行までの待機時間には、Retry-Afterの値(またはX-RateLimit-Reset - now)を使用してください。
クライアント実装のガイダンス
Retry-Afterを守ってください。これをバックオフの最小値とし、その上にジッター付きの指数バックオフ(5s → 10s → 20s → 40s ± random)を重ねることで、同時に429を受けた2つのクライアントが同期して再試行しないようにします。- 再試行は少ない上限回数で打ち切ってください(例: 5回)。エラーを呼び出し元に返し、チームにアラートを通知してください。429が継続的に発生する場合、一時的なスパイクではなく、制御不能なループが原因であることがほとんどです。
- ワークロードごとに1つの識別子を使用してください。1つの
x-api-keyを多数のバックエンドで共有すると、それらが同じカウンターにまとめられ、1つの負荷の高いバックエンドが他のバックエンドのリクエスト枠を使い果たす可能性があります。環境、ブランド、顧客ごとに別のアプリケーション(つまり別のapi_key)を発行してください。詳しくはプログラムによる登録を参照してください。 - 判定の読み取り結果をキャッシュしてください。
/decision/エンドポイントは、短い間隔でのポーリングループを想定して設計されていません。リアルタイムの更新が必要な場合はWebhookを使用し、GET /v3/session/<id>/decision/はバックフィルや監査の目的でのみ呼び出してください。 - PDFはオフラインで生成してください。PDFのレンダリングはCPU負荷が高い処理です(上限50/min)。ページが表示されるたびに生成するのではなく、セッションが終了ステータスに達した後にキューを介してトリガーしてください。
429に対応したクライアントのサンプル
より大きな上限が必要な場合
マーケティング施策の開始やバックフィルなどで1分あたり600セッションでは足りない場合は、applicationのUUIDと、想定される継続的なレートおよびバーストレートを添えてsupport@didit.meまでメールでご連絡ください。上限の変更はアプリケーションごとに設定されます。