メインコンテンツへスキップ
429 のエラーコードと reason を読めば、どの制限でリクエストが止められたかがわかります。そのうえで Retry-After の分だけ待つか、制限を変更してください。ルーティングとフォールバックはプロバイダーの障害を減らしますが、プロバイダー、またはワークスペースやキーのポリシーによってリクエストがスロットリングされることは引き続きあります。 これらはすべて 429 を返します。Gateway のクォータ適用が一時的に利用できない場合は、代わりに再試行の案内付きで 503 を返します。

Gateway の制限

各ワークスペースの各ユーザーには、直近 1 分間で計測される 1 分あたりのリクエスト利用枠があります。同じユーザーが作成した API キーはこの利用枠を共有します。OAuth リクエストはサインインしているユーザーの利用枠で計数され、所有者のないキーはワークスペース単位の利用枠を 1 つ共有します。 利用枠は、ワークスペースの実績が積み重なるにつれて自動的に引き上げられます。ワークスペースには条件を満たす最も高い行が適用され、変更は数分以内に反映されます。 無料モデルには、デフォルトで UTC の 1 日あたり 1,500 リクエストの利用枠もあります。この利用枠はすべての無料モデルと、同じユーザーがリクエストを送信するすべてのワークスペースで共有されます。有料モデルのリクエストはこの利用枠を消費しません。受け付けられた無料リクエストは、その後プロバイダーが失敗しても計数され、1 つのリクエスト内のプロバイダーフォールバックは 1 回として計数されます。 どちらの制限も Gateway のリージョンをまたいで適用され、特定のユーザーとワークスペースについて引き上げることができます。ファイル操作とジョブステータスのポーリングは 1 分あたりの利用枠を使いますが、管理エンドポイントは使いません。 拒否されたリクエストは、秒数の Retry-After 付きで 429 を返します。その時間だけ待ってから再試行してください。

管理 API の制限

/v1/keys、/v1/logs、/v1/analytics などの管理エンドポイントは、認証情報ごとに 1 分あたり 200 ユニットの利用枠を共有します。管理キー、OAuth トークン、ダッシュボードのセッションはそれぞれ独自の利用枠を持ち、認証情報のないリクエストは IP アドレスごとに 1 つの利用枠を共有します。モデル、ファイル、バッチ、ジョブのエンドポイントはこの利用枠を使いません。 各リクエストは、処理の重さに応じてユニットを消費します。 /v1/health と CORS のプリフライトリクエストは無料です。利用枠を超えたリクエストは、rate_limit_exceeded、reason management_api_rate_limit、Retry-After: 60 付きで 429 を返します。計数は概算で、これらのレスポンスには x-ratelimit-* ヘッダーが付かないため、一括処理のスクリプトは上限まで実行せず、時間を分散させてください。

キーの上限と予算

API キーの日次、週次、月次のリクエスト数と支出の上限、およびワークスペースの予算に達すると、429 と key_limit_exceeded が返されます。本文の reason、limit_window、reset_at で、どの制限に達したか、その期間がいつリセットされるかがわかり、Retry-After にはそれまでの秒数が入ります。 生涯予算やソフトブロックされたキーのように、制限が自動でリセットされない場合は Retry-After がありません。再試行せず、ワークスペースの予算を引き上げるか、キーの上限を引き上げるか、別のキーを使ってください。 ワークスペースのオーナーと管理者は、管理キーを使った /v1/budgets API または 設定 → 予算 で予算を管理します。この画面には、各予算のこれまでの支出、使用率、期間の予測、リセット日時が表示されます。日次、週次、月次の予算は UTC の区切り(午前 0 時、月曜日の 00:00、毎月 1 日)でリセットされます。 支出アラートを使うと、これらの制限に達する前に警告を受け取れます。ブロックに設定された支出ルールは、429 と spend_rule_blocked を返します。これはベストエフォートで、支出が上限を超えてから数分後に始まるため、正確な上限にはキーの上限と予算を使ってください。x-phaseo-spend-warning ヘッダーは、この後ブロックされる可能性があることを示します。

部門の予算

オーナーと管理者は、phaseo department-budgets、/v1/department-budgets API、設定 → 予算、または Terraform プロバイダーの phaseo_department_budget リソースで部門の予算を管理します。部門の支出は、部門のレート制限と同じキーと OAuth リクエストを計数します。 部門が日次、週次、または月次の予算を使い切ると、その部門に計数される API キーのリクエストは、429、key_limit_exceeded、理由 department_daily_cost_budget_reached、department_weekly_cost_budget_reached、または department_monthly_cost_budget_reached を返します。本文の department_id と department_name で部門を特定でき、reset_at と Retry-After で予算がいつリセットされるかがわかります。
  • 予算の確認が一時的に利用できない場合、リクエストは許可されるため、部門が短時間だけ予算を超えて支出することがあります。
  • オーナーと管理者には、予算の約 80% の時点と 100% の時点でモバイルのプッシュ通知が届きます。これらのアラートのために予算は 15 分ごとに確認されるため、100% のアラートが届く前にリクエストが拒否されることがあります。

レート制限ポリシー

ワークスペースの管理者は、requests_per_minute、tokens_per_minute、concurrent_requests を設定する名前付きポリシーを作成し、キー、メンバー、部門、エンドユーザーに割り当てることができます。管理には、phaseo rate-limits policies と phaseo rate-limits assignments、/v1/rate-limits API、設定 → レート制限、または Terraform プロバイダーの phaseo_rate_limit_policy と phaseo_rate_limit_assignment リソースを使います。 部門に計数されるもの。 部門に紐付けられたキーは、その部門にのみ計数されます。それ以外のキーは作成者が所属するすべての部門に計数され、OAuth リクエストはそのユーザーのすべての部門に計数されます。部門のオーバーライドが設定されたメンバーは、オーバーライド先の部門にのみ計数されます。これらのキーと OAuth リクエストをその人の主部門にのみ計数するには、設定 → 通知、または管理キーを使った PATCH /v1/notifications/settings の spend.department_attribution で部門の帰属を primary に設定します。部門の予算と支出ルールも同じ設定を使います。 複数のポリシーが適用される場合は、それぞれが計数され、最初に上限に達したものがリクエストを拒否します。ポリシーは Gateway の制限に加えて適用されます。ポリシーの変更は約 1 分以内に反映されます。ダッシュボードまたは SCIM による部門メンバーシップの変更は、反映まで最大約 5 分かかることがあります。

1 分あたりのリクエスト数とトークン数

どちらも直近 1 分間で計測されます。tokens_per_minute は、各リクエストの入力トークンと出力トークンを完了時に計数します。トークンを使用したストリーミングリクエストや失敗したリクエストも含まれます。直近 1 分間の使用量が上限に達した時点でリクエストは拒否されるため、すでに処理中のリクエストによって使用量が上限を超えることがあります。1 つのリクエスト内のプロバイダーフォールバックは 1 回として計数されます。 拒否されたリクエストは、429、rate_limit_exceeded、理由 policy_requests_per_minute または policy_tokens_per_minute、policy_id、limit_scope(key、member、department、workspace、end_user)、秒数の Retry-After を返します。 ポリシーの対象となるリクエストのレスポンスには、最も厳しい制限のヘッダーが付きます。 拒否されたリクエストには、拒否した制限のヘッダーのみが付きます。計数はバックグラウンドで行われるため remaining は概算で、トークンのヘッダーには現在のリクエスト自体の使用量はまだ含まれません。

同時リクエスト数

concurrent_requests は、同時に処理できるリクエスト数の上限です。リクエストは受け付けられた時点から、レスポンスがすべて送信されるまで(ストリーミングレスポンスの場合はその全体)1 つの枠を占有します。リクエスト内のプロバイダーとモデルのフォールバックはその枠を共有します。すべての枠が使用中の場合、リクエストは理由 policy_concurrent_requests と Retry-After: 1 で拒否されます。 同時実行数の制限を確認する際はポリシーのカウンターを待つため、わずかにレイテンシーが増えます。解放が失われた枠は 15 分後に自動で解放されます。バッチとリアルタイムセッションは制限されず、動画生成は、それを開始するリクエストが処理中の間だけ枠を占有します。

厳格なポリシー

デフォルトでは、ポリシーはフェイルオープンです。制限を確認できない場合、リクエストは許可されます。厳格にするには fail_closed を設定します。厳格なポリシーは、リクエスト数とトークン数の制限をバックグラウンドではなくリクエスト送信前に確認します。これにより正確になりますが、レイテンシーが増えます。2 秒以内に確認できない場合、リクエストは理由 policy_unavailable で拒否されます。 同時実行数による拒否と policy_unavailable による拒否には、x-ratelimit-* ヘッダーは付きません。

プロバイダーの制限

BYOK リクエストには、ご自身のプロバイダーアカウントの制限が適用されます。マネージドリクエストは共有のプロバイダー容量を使い、これはワークスペースに割り当てられた利用枠ではありません。 プロバイダーが Retry-After を送信した場合、Phaseo は検証したうえで転送します。BYOK のレスポンスには X-Phaseo-Upstream-RateLimit-* ヘッダーが含まれることもあります。マネージドリクエストでは共有容量を表すため省略されます。その他の上流のヘッダーは転送されません。プロバイダーの 429 コードについてはエラーコードを参照してください。

スロットリングされたリクエストに対処する

  1. エラーコードを読み、一時的なスロットリングなのか、設定変更が必要な上限、予算、ポリシーなのかを判断します。
  2. Retry-After がある場合は従います。秒数または HTTP 日付のどちらかなので、再試行をスケジュールする前に検証してください。
  3. ない場合は、ジッター付きで最大遅延を設けた指数バックオフを使います。
  4. 試行回数と全体の期限で再試行を制限します。再試行の前に、放棄した処理をキャンセルし、失敗した各レスポンスの本文を解放します。
  5. スロットリングが続く場合は、同時実行数を減らします。
結果が不明なジョブの送信を自動で再試行したり、完了したツール操作を再実行したりしないでください。クライアントがレスポンスを受け取れなくても、リクエストはプロバイダーに届いている可能性があるため、再試行すると処理と課金が重複することがあります。受け付けられた動画ジョブやバッチジョブは、再送信せずにステータスエンドポイントを使ってください。 スロットリングを監視するには、エンドポイントとモデルごとの 429 の割合を追跡し、リクエストログでフォールバックの頻度を確認します。これらをルーティング設定と、BYOK トラフィックの場合はプロバイダーアカウントのクォータと比較してください。ガードレールでは、どのキーがどのモデルとプロバイダーを使えるかを制御します。
最終更新日 2026年11月13日