基本概念

レート制限

同時実行数、待機キュー、API の送信頻度にはそれぞれ上限があります。generation_limits が返された場合は、現在の利用枠と件数を確認できます。

同時実行の上限に達したとき

待機キューに空きがあれば、受け付けたジョブは queued として待機します。実行中のジョブが終了すると、待機中のジョブが順に開始されます。

フィールド意味
concurrency_limit同時実行の上限。
active_generation_jobs実行中のジョブ数。
queued_jobs_limit待機キューの上限。
queued_generation_jobs待機中のジョブ数。
queue_capacity_remainingキューの残り容量。
wave_size_hint一度に送信する件数の目安。

キューが満杯になったとき

受付枠に空きがないと 429 と retry-after を返します。

{
  "error": {
    "code": "queue_full",
    "message": "受付枠が埋まっています。retry-after 後に同じ入力と冪等性キーで再試行してください。",
    "request_id": "req_00000000000000000000000000000000",
    "category": "capacity",
    "stage": "admission",
    "retryable": true,
    "retry_after_seconds": 30,
    "public_reason": "queue_full",
    "next_action": "retry_later"
  }
}

待機時間を守り、同じ入力と冪等性キーで再送します。利用可能な件数を固定値で埋め込まないでください。

エンドポイントのリクエスト制限

生成の同時実行数とは別に、API の呼び出し頻度も制限されます。

ヘッダー意味
ratelimit-limit現在の期間で許可されるリクエスト数。
ratelimit-remaining残りのリクエスト数。
ratelimit-resetリセットまでの秒数。
retry-after再試行まで待つ秒数。
x-orchestor-poll-after状態取得まで待つ秒数。

クライアント側の対処

  • 429 では retry-after の時間を待ってから再送します。
  • ワーカープールなどで送信量を抑え、キューを満杯にしないようにします。
  • 受付済みジョブは終端状態になるまで追跡します。
  • 再試行には指数バックオフとランダムな待ち時間を使います。
  • ポーリングの頻度と生成の同時実行数を別々に管理します。
  • 複数ワーカーでもワークスペース全体の枠を共有します。
現在の上限を使う

generation_limits は null の場合もあります。値がないときに無制限と解釈せず、応答のヘッダーと再試行指示に従ってください。

関連ページ