レート制限とクォータ

すべての利用者のためにAPIを高速に保つため、2種類の上限があります。

• キーのレート制限：1秒あたりに送信できるリクエストの数。短いピークのためのバーストがあります。
• 組織のクォータ：組織のすべてのキーを合わせて、1分、1日、1か月あたりに送信できるリクエストの数。

どちらも組織のプランによって決まります。各レスポンスで現在の状況がわかるので、行儀のよいクライアントが推測する必要はありません。

キーのレート制限

キーごとに、一定のレートとバーストがあります。バーストの数までのリクエストは一度に送信でき、その後は一定のレートでリクエストが許可されます。

クラスは組織のプランで決まります。GET /v1/meは、呼び出したキーのクラス、レート、バーストを示します（rate_limit）。リクエストを処理するAPIサーバーがいくつあっても、上限はキー全体に対して適用されます。

ストリーミングのエンドポイント、つまりPOST /v1/chat（"stream": trueの有無を問わず）とGET /v1/jobs/streamは、キーのレート制限の対象外です。キーのレートを消費せず、RateLimitヘッダーには"key"の項目がありません。ただし組織のクォータには、リクエストの開始時にそれぞれ1回として数えられます。質問には独自の上限があり、後述します。

組織のクォータ

プランでは、組織のリクエストのクォータを1分、1日、1か月単位で設定できます。ウィンドウはUTCの暦の期間です。1分は0秒に、1日はUTCの00:00に、1か月は1日のUTCの00:00に始まります。組織のキーまたはOAuthトークンを使ったリクエストは、どのアドレスに送信したものでもすべて数えられます。ストリーミングのリクエストは、どれだけ長く続いても、開始時に1回として数えられます。クォータを使い切っている場合は、ほかのリクエストと同じく429で拒否されます。429で拒否されたリクエストは数えられません。

ヘッダー

キーを使ったリクエストへのレスポンスには、すべて、そのリクエストに適用される上限が含まれます。

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-PolicyとRateLimitは、IETFのドラフトRateLimit header fields for HTTPに従います。各項目が1つの上限を表します。

X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetは、RateLimitができる前に書かれたクライアントのために、これらの上限のうち最も厳しいものを簡単な形で伝えます。X-RateLimit-Resetの単位は秒です。

上限に達したとき

APIは、秒単位のRetry-Afterヘッダー付きで429 Too Many Requestsを返します。

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Retry-Afterの時間だけ待ってから、リクエストを繰り返してください。POSTとPATCHは同じIdempotency-Keyで繰り返します。エラーの再試行のヘルパーは、その両方を行います。

プランのその他の上限も、Retry-After付きで429を返します。たとえば1日あたりの質問の数（limits.questions）や、同時に生成中の回答の数（limits.concurrent_answers）です。これらも同じように扱ってください。

上限を超えないために

• 429を待つのではなく、RateLimitを読み、rが少なくなったら速度を落としてください。
• 大量の処理は時間を分散させ、バッチ用のエンドポイントがあれば使ってください。100件のドキュメントのバッチは1回のリクエストです。
• 変更を短い間隔のループでポーリングしないでください。Webhookを購読するか、数秒ごとにイベントフィードを読み込んでください。
• 並行して動くワーカーには、共有のレート制限の仕組みを使ってください。1つのキーを使う複数のプロセスは、1つのレート制限を共有します。
• 連携システムにもっと多くのリクエストが必要なら、Sursaの担当窓口に上位のクラスについて問い合わせてください。