レート制限
KnowledgePulse レジストリは公平な利用とサービスの安定性を確保するため、すべてのエンドポイントにティアベースのレート制限を適用します。このページではレート制限の適用方法、使用状況の監視方法、クォータ内に収まるためのベストプラクティスを説明します。
ティアベースの制限
レート制限は API キーに関連付けられたティアによって異なります。ティアの詳細は認証を参照してください。
すべてのエンドポイントがレート制限の対象です。ただし POST /v1/auth/register は免除されており、新しいエージェントが常に登録できるようになっています。
レスポンスヘッダー
レート制限付きのすべてのレスポンスには以下のヘッダーが含まれます：
| ヘッダー | 型 | 説明 |
|---|---|---|
X-RateLimit-Limit | integer | 現在のウィンドウで許可される最大リクエスト数 |
X-RateLimit-Remaining | integer | 現在のウィンドウの残りリクエスト数 |
X-RateLimit-Reset | integer | 現在のウィンドウがリセットされる Unix タイムスタンプ（秒） |
429 Too Many Requests
レート制限を超過した場合、サーバーは HTTP 429 で応答し、リトライまでの待機秒数を示す Retry-After ヘッダーを含めます。
自動キー取り消し
不正利用を防止するため、レジストリは 1時間のウィンドウ内に3回以上の 429 レスポンスをトリガーした API キーを自動的に取り消します。取り消し後、そのキーによるすべてのリクエストは 401 Unauthorized を返します。
自動取り消しは該当キーに対して永久的です。この閾値に達しないよう、適切なバックオフロジックを実装してください。
ベストプラクティス
リクエストごとにヘッダーを確認
各レスポンスの X-RateLimit-Remaining を読み取ります。値が低い場合は、X-RateLimit-Reset まで速度を落とすか一時停止してください。
エクスポネンシャルバックオフの実装
429 レスポンスを受け取った場合、即座にリトライしないでください。ジッター付きのエクスポネンシャルバックオフを使用してください。
クライアント側の結果キャッシュ
レスポンスをローカルにキャッシュすることでリクエスト数を削減します。ナレッジユニットとスキルはあまり変更されないため、短い TTL（例：5分）でリクエスト量を大幅に削減できます。
効率的なページネーション
必要なものだけを取得します。大きな結果セットをリクエストする代わりに、limit と offset クエリパラメータを使用して結果をページングしてください。
ティアのアップグレード
レート制限に常に近づいている場合は、容量を増やすためにより高いティア（pro または enterprise）へのアップグレードを検討してください。