レート制限

レート制限は短時間に送れる要求数の上限です。超えると処理せず 429（要求過多）で待ち時間を伝えます。暴走するスクリプトを防ぐ安全策で、生成総量の枠ではありません。

制限の一覧

アカウントごとの 2 つの枠：読み取りと書き込み

/api/v1/* と互換の /v1/*、/v1beta/* は、キーでなくアカウント単位で制限します。キー単位なら増やすだけで回避できるためです。

読み取りと書き込みは、同じ量の別々の枠で数えます。初期の保護しきい値は各 10 秒で 1,000 要求、持続する速度で約 100 RPS（毎秒の要求数）、一時的に 1,000 件です。通常の有料生成を少量に制限する枠ではなく、不正利用やクライアントの暴走を防ぐ大きな保護枠です。

固定時間窓ではなくトークンバケットです。容量 1,000 を 10 秒で補充し、毎秒約 100 トークンが戻ります。各要求が 1 つ使い、継続的に補充します。固定窓と違い、期間の境界でも滑らかに戻ります。

upload-url には書き込み枠に加え、独自の 10 秒で 1,000 要求の保護があります。オブジェクト保存への書き込み許可を別に守り、通常は届かない量です。

usage は逆に、読み取り枠に加えて 1 分で 30 要求という厳しい枠があります。履歴を集計し、通常の読み取りより処理が重いためです。照合用で、ポーリングには使いません。この枠は判定不能時に常に 429 を返します。他の枠で通過する設定ができても、これは許可側に倒れません。

未使用のアップロード URL

別途、1 アカウントの発行済みで未使用の URL は最大 128 件、申告サイズの合計は 1 GiB です。追加要求は 429 と Too many pending uploads; finish existing uploads before requesting more を返し、Retry-After はありません。

待つだけでは解消しないので、汎用再試行を回し続けないでください。発行済みをアップロードして確定するか、約 20 分の URL 期限が切れると、その分の余地が空きます。多くは、スクリプトが URL を大量発行して未使用のままにする問題です。メディア参照。

すべての枠

制限はインターフェース単位で適用し、同じ範囲の要求は共通の処理を通ります。API 利用者が関係するのは最初の 5 つです。

初期値はリリースなしで変更できます。現在値は X-RateLimit-Limit とコンソールの概要にあります。ヘッダーを基準にし、クライアントに初期値を固定しないでください。

応答ヘッダー

初期値のアカウントの通常応答には、次が付きます。

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997

制限時の応答

{
  "code": 429,
  "msg": "Too many requests. Retry in a moment",
  "request_id": "req_…"
}

HTTP は 429、Retry-After 付きです。

対処

Retry-After を読みます。 固定間隔で連打しません。例は 5 回で止まり、前述の未使用アップロードの 429 も無限に回りません。

async function callRespectingLimits(url, init) {
  for (let i = 0; i < 5; i++) {
    const res = await fetch(url, init);

    if (res.status !== 429) return res;

    // The server already told you how long to wait; don't guess
    const wait = Number(res.headers.get('retry-after') ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error('persistently rate-limited');
}

import time, requests


def call_respecting_limits(method: str, url: str, **kwargs) -> requests.Response:
    for _ in range(5):
        res = requests.request(method, url, **kwargs)

        if res.status_code != 429:
            return res

        # The server already told you how long to wait; don't guess
        time.sleep(float(res.headers.get("retry-after", 1)))

    raise RuntimeError("persistently rate-limited")

同時実行数は別の問題

進行中タスクを制限するのは次で、いずれもレート制限ではありません。

• 利用可能残高： 全進行中タスクが資金を予約します。尽きると新規は 40201。
• 支出上限： キーの日次・月次・累計、所属チームの日次・月次、プラットフォームの日次です。どれかに達すると 40202。支出上限参照。
• 実行容量： モデルをまったく実行できない場合は 50301。

「同時にもっと動かしたい」への答えは通常、レート制限でなく残高追加か支出上限の変更です。

増量を相談する

コンソールの概要で現在値を見られます。サポートの API 連携 で、最大の毎秒要求数、バッチの有無と規模を伝えます。審査を早められます。

それまでは同時呼び出しに上限を設け、Retry-After に従います。初期レートに合わせて不自然に低くせず、作業、生成時間、残高から同時数を決めます。

制限の仕組み自体が利用不能な場合

レート制限は外部カウンターに依存します。失敗時は設定により、許可して継続するか、拒否して枠を守ります。初期設定は拒否です。「設定を読めない」が「無制限」になってはいけません。

拒否設定では 500 でなく 429、Retry-After: 1 です。500 は障害を意味し、多くの SDK が即時再試行して負荷を増やすためです。429 と Retry-After は、必要な待機を伝えます。

429 を速く送りすぎた証拠と決め付けないでください。 どちらの場合も、Retry-After に従うのが適切です。