メインコンテンツまでスキップ

レート制限

API は、テナントごとにご契約に基づいて設定された秒間リクエスト数の上限でレート制限を適用します。現在の上限は StoryHubフィード管理画面 の請求タブ、または各レスポンスの X-RateLimit-Limit ヘッダーで確認できます。

エンドポイント別の追加制限​

一部のエンドポイントは、テナント全体のレート制限に加えて、専用の低 RPS リミッターが適用されます。

エンドポイント上限理由
POST /v1/push-candidates1 RPS / burst 51 回の呼び出しで大量の非同期処理が起動するため

両者は独立に評価されるため、テナント全体の上限に残量があっても専用リミッター側で 429 を返す場合があります。

レスポンスヘッダー​

すべての API レスポンスにレート制限の情報が含まれます：

ヘッダー説明
X-RateLimit-Limitご契約の秒間最大リクエスト数
X-RateLimit-Remaining現在のウィンドウ内の残りリクエスト数
X-RateLimit-Reset現在のウィンドウがリセットされる Unix タイムスタンプ
Retry-Afterリトライまでの待機秒数（429 の場合のみ）

レート制限への対応​

制限を超過すると、API は 429 Too Many Requests を返します：

{
  "type": "https://feed.storyhub.studio/probs/rate-limit",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Rate limit exceeded. Try again in 1 second.",
  "instance": "/v1/feed"
}

推奨されるアプローチ：

  1. リクエスト前に X-RateLimit-Remaining を確認してください。
  2. 429 を受け取った場合は、Retry-After で指定された時間だけ待機してください。
  3. リトライロジックには Exponential Backoff を実装してください。

ベストプラクティス​

  • レスポンスをキャッシュする — API コールの回数を削減できます。
  • イベントをバッチ送信する — POST /v1/events リクエストで最大 100 件のイベントを一括送信してください。
  • リクエストを均等に分散する — バースト的な送信を避けてください。
  • より高い制限が必要な場合は、お問い合わせください。