レート制限とフェイルオーバー

リクエストがモデルに届くまでには、3 つの要素が関わります。キーに設定した制限、モデルを提供するチャネルの容量、そしてそれらのチャネルの健全性です。容量と健全性の問題の多くは、短時間のキュー待ちと別チャネルでの再試行によって、ゲートウェイ自身が吸収します。クライアントに届くのは、再試行可能な短い 429 または 502 だけです。

キーに設定する制限#

各キーには、1分あたりのリクエスト数 と 最大同時リクエスト数 の制限を設定できます。API キーでキーを作成または編集するときに、上限と制限 で設定します。どちらも既定ではオフです。

制限に達したリクエストは、空きが出るまで最大 2 秒待ちます。空きが出なければ、429、メッセージ This API key has reached its rate or concurrency limit.、秒単位の retry-after ヘッダーとともに失敗します。あるワークロードが別のワークロードの枠を使い切ってしまわないよう、それぞれ独自の制限を持つ別々のキーを使ってください。その他のキー設定については API キーを参照してください。

容量待ちのキュー#

各チャネルが同時に処理できるリクエストの数には上限があります。リクエストの送り先となるチャネルが満杯の場合、ゲートウェイはそのモデルを提供する他のチャネルを試します。すべてが満杯の場合、リクエストは最も早く空きが出ると見込まれるチャネルのキューに入ります。

容量の空きを待つ時間は、合計で最大 10 秒 です。受け付けられた場合、レスポンスには待機時間を示す x-lovely-queued-ms が含まれます。受け付けられなかった場合は、429、メッセージ All upstream capacity for this model is busy. Retry shortly.、retry-after ヘッダーとともに失敗します。

キューで待っているリクエストは、実行されるまで課金されません。429 で拒否されたリクエストは一切課金されません。

自動フェイルオーバー#

チャネルが失敗すると、ゲートウェイは同じチャネルグループ内の別のチャネルでリクエストを再試行します。1 リクエストあたり最大 3 回まで試行します。フェイルオーバーするのは、チャネルが次のような場合です。

• タイムアウトした、到達できない、または 408、409、425、429、任意の 5xx を返した。
• クライアント側ではなくチャネル側の理由でリクエストを拒否した。
• ストリーム中、最初のトークンより前に失敗した（ストリーミングを参照）。

新しい会話は、そのモデルを提供する複数のチャネルに分散されます。エラーが多いチャネルや、普段より応答が大幅に遅くなっているチャネルは、回復するまで新しい会話の割り当てが少なくなります。失敗が続くチャネルは一定期間ローテーションから外され、以降のリクエストはそのチャネルを避けます。そのチャネルに固定されていた会話は、正常なチャネルに移ります。

次の 2 つのケースは決して再試行されません。

• リクエスト自体が無効な場合。 モデルが 400、404、413、422 で拒否した場合、別の場所で再試行しても同じように失敗します。そのステータスと理由が返ります。
• ストリームが開始済みの場合。 最初のトークン以降、リクエストはそのチャネルに確定します。その後の失敗は、ストリーム内のエラーイベントとして届きます。

ステータスコード#

エラーの種類はお使いの API 形式に従います。429 では rate_limit_error（Anthropic）、rate_limit_exceeded（OpenAI）、RESOURCE_EXHAUSTED（Gemini）、502 では api_error（Gemini では UNAVAILABLE）です。完全な一覧はエラーにあります。

クライアントで再試行する#

ゲートウェイはすでにチャネルをまたいで再試行しているため、429 や 502 が返るのは、何度か試行しても問題が解消しなかったことを意味します。指数バックオフとジッターを入れてさらに数回再試行し、retry-after がある場合はそれに従ってください。

Anthropic SDK と OpenAI SDK は既定でこれを行い、408、409、429、5xx を 2 回再試行します。バッチジョブでは上限を引き上げてください。

import os
from openai import OpenAI

client = OpenAI(base_url="https://lovelyrouter.com/v1", api_key=os.environ["LOVELY_API_KEY"], max_retries=5)

素の HTTP を使う場合は、同じポリシーを実装します。

# --retry covers 429 and 5xx and honors retry-after
curl --retry 5 --retry-max-time 120 https://lovelyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model": "gpt-6.1-sol", "messages": [{"role": "user", "content": "Hi"}]}'

ストリームの場合は、コンテンツが届く前にエラーが返ったときだけ再試行してください。ストリームが途中で切れた場合、部分的な出力の分はすでに課金されています。その出力を残すか、回答全体をもう一度リクエストするかを判断してください。

残高と利用上限#

すべてのリクエストは、実行前に残高とキーの利用上限を確認します。残高が 0 以下の場合、またはキーが上限まで使い切っている場合、リクエストは 402 と Insufficient balance. Top up at the dashboard. または This API key has reached its spend limit. で失敗します。エラーの種類は、OpenAI 形式では insufficient_quota、Anthropic 形式では billing_error、Gemini 形式では RESOURCE_EXHAUSTED です。

確認はリクエストの開始時に行われ、請求はリクエストの終了から数秒後に確定します。残高がプラスの状態で開始したリクエストは必ず最後まで実行されるため、残高がわずかにマイナスになることがあります。その分は次のチャージで相殺されます。クレジットと請求を参照してください。