レート制限
レート制限は、アプリケーションが指定された時間内に API に対して行えるリクエストの最大数を定義します。このメカニズムはサービスの全体的な健全性と信頼性を維持するために不可欠です。
レート制限を使用する理由
- 1 つのクライアントが過剰なリクエストでサーバーに負荷をかけるのを防ぎます。
- すべてのクライアントに対して一貫した予測可能なレスポンスタイムを確保します。
- バックエンドサービスを予期しないトラフィックの急増から保護します。
- インフラストラクチャ上で安定した制御された負荷パターンを維持します。
- ブルートフォースなどの攻撃の試みに対する防御を強化します。
- 分散型サービス拒否（DDoS）のリスクを軽減します。
- 不適切に実装されたインテグレーションによる影響を軽減します。
- 侵害された API 認証情報による潜在的な損害を制限します。
- すべてのクライアントに対して API リソースへの均衡なアクセスを確保します。
- 一部による乱用が他のユーザーのエクスペリエンスを低下させるのを防ぎます。
- ビジネス基準とニーズに応じてトラフィックを優先させることができます。
- より効率的で持続可能な API 消費の実践を促します。
レート制限の仕組み
各 API 呼び出しは、許可されたリクエスト毎秒（RPS）制限にカウントされます。デフォルト値はテナントあたり 10 RPS です。制限を超えると、API は HTTP 429 Too Many Requests を返します。
正確な制限はテナントごとに設定されます。高スループットのインテグレーションをサイジングする前に、オンボーディングチームに連絡してアカウントに適用される制限を確認してください。
429 エラーの処理
オペレーションのリクエスト量が増加する場合（一時的または恒久的に）、Unico チームに通知して環境のレート制限を引き上げてもらってください。このリクエストは、アプリケーションが動作不能になるのを避けるために、実際に量が増加する 前 に行う必要が あります。
- コードを監査して非効率な API 使用パターンを特定してください。
- 意図しないループや冗長な API 呼び出しを確認してください。
- 大きなバーストで送信する代わりに、リクエストを時間的に均等に分散してください。
- ほとんど変化しない頻繁にアクセスされるデータをキャッシュしてください。
- OAuth2 アクセストークンをその完全な 1 時間の TTL で使用してください — リクエストごとに
POST /oauth2/tokenを呼び出さないでください。 - 適切なキャッシュ無効化戦略を実装してください。
GET /client/v1/process/\{id\} をポーリングする代わりに、PROCESS_STATE_FINISHED の Webhook とイベント にサブスクライブしてください。ポーリングループは高トラフィック時に GET プロセスの予算を簡単に使い果たしてしまう可能性があります。
制限に達したときの動作
プラットフォームは以下を返します:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
| ヘッダー | 意味 |
|---|---|
Retry-After | 再試行前に待機する秒数。必ず遵守してください。 |
Retry-After がない場合は、60 秒を上限に指数バックオフ（1 秒、2 秒、4 秒、8 秒、...）にフォールバックしてください。
並列処理に関する考慮事項
レート制限は毎分のリクエスト数を制限しますが、プラットフォームはインフラストラクチャレベルでも 並列処理の上限 があります。100 リクエスト/分の予算があっても、同じ秒に 100 件すべてを送信すると、1 分間に分散させるよりも拒否される可能性が高くなります。
高スループットのインテグレーションでは、バーストではなく安定した RPS を目標にしてください。
Magic Link Webhook の配信
Trully には Webhook V2 専用の配信クォータがあります。Webhook サーバーは 1 分 以内に応答することが期待されています。それより遅い応答は破棄されます（ユーザーのプロセスは影響を受けません）。一貫した処理のために、Webhook を素早く確認応答し、非同期で処理してください。
次のステップ
- 認証 — トークンキャッシュ戦略。
- Webhook とイベント — ポーリングをプッシュに置き換える。
- エラーコード > 再試行ポリシー — 再試行する場合（およびしない場合）。