エラー

Lovely Router は標準的な HTTP ステータスコードを使います。2xx は成功、4xx はリクエストの修正（またはアカウントへのチャージ）が必要なこと、5xx や 429 は再試行する価値のある一時的な問題を意味します。ボディには、呼び出した API の形式で理由が示されるため、公式 SDK はいつもの例外を送出します。

ステータスコード#

その他の 5xx は 502 と同じように扱ってください。モデルに届く前に拒否されたリクエストのエラー（不正な JSON による 400、401、402、403、不明なモデルによる 404、キーの制限による 429）は課金されません。

モデルのエンドポイントのエラーボディ#

モデルのエンドポイントは、呼び出した API の形式でエラーを返します。以下の各タブは同じ 401 を示しています。

{"type": "error", "error": {"type": "authentication_error", "message": "Invalid or revoked API key"}}

ステータスコードごとのエラーの type（Anthropic と OpenAI）または status（Gemini）：

Gemini のボディでは、error.code は常に HTTP ステータスと同じ値です。分岐には status の文字列ではなく、ステータスコードを使ってください。不明なエンドポイントや予期しないゲートウェイのエラーなど、リクエストを読み込む前に発生したエラーも、呼び出したエンドポイントの形式で返されます。

表示される可能性のあるメッセージ#

モデルに届く前に拒否されたリクエスト（無効なキー、残高不足、不明なモデル）も含め、すべてのエラーレスポンスに x-lovely-request-id ヘッダーが付きます。サポートに問い合わせる際は、この ID をお知らせください。

ツールとブラウザエージェントのエラーボディ#

/v1/tools と /v1/browser は、すべてのエラーを 1 つの形式で返します。機械が読み取るための type と、人が読むためのメッセージです。

{"error": {"type": "insufficient_quota", "message": "Insufficient balance: this run can cost up to $0.3000 (100 results). Lower max_results or top up."}}

開始後に失敗した実行は、HTTP エラーにはなりません。実行オブジェクトが、status を failed、timed_out、stopped のいずれかにし、error メッセージを付けて返ります。支払いは返された結果の分だけです。ツールを実行するを参照してください。

ストリーミング中のエラー#

ストリームが始まった時点でステータスはすでに 200 になっているため、エラーはストリーム内のイベントとして届きます。最初のトークンより前の失敗は別のチャネルで再試行されるため、通常はストリームが成功するか、通常の HTTP エラーで失敗するかのどちらかです。

ストリームの途中でモデルが 3 分間データを送らなくなった場合、Lovely Router はそのストリームの形式のエラーイベントでストリームを終了します。

event: error
data: {"type": "error", "error": {"type": "api_error", "message": "Upstream stopped responding mid-stream"}}

実行中のストリームの中でチャネルが報告したエラーは、同じ形式の汎用的なイベント（Responses API の場合は {"type": "error", "code": "server_error", "message": "…"} のような error イベント）に置き換えられるため、チャネル独自の文言が届くことはありません。チャネルが混雑または過負荷の場合は、Anthropic では overloaded_error、OpenAI では rate_limit_exceeded、Gemini では RESOURCE_EXHAUSTED となり、メッセージは Upstream capacity for this model is busy. Retry shortly. です。それ以外のエラーは api_error（Gemini では UNAVAILABLE）となり、メッセージは The model provider returned an error. Please retry. です。リクエストは最初から再試行してください。すでにストリーミングされた出力は課金されます。

失敗したリクエストを再試行する#

Lovely Router は、失敗したモデルのリクエストをエラーとして返す前に、すでに別のチャネルで再試行しています。それでも吸収しきれないケースに備えて、クライアント側でも再試行してください。

• 429、500、502、503、504 とネットワークエラーは再試行します。
• retry-after ヘッダーがある場合は、その秒数だけ待ちます。ない場合は、1、2、4、8 秒…と指数的にバックオフし（上限 30 秒）、クライアントが一斉に再試行しないよう最大 1 秒のランダムなジッターを加えます。
• 約 5 回試行したらやめて、エラーを呼び出し元に返します。
• 400、401、403、404、409、413、422 は、リクエストを変更せずに再試行しないでください。402 はチャージした後にのみ再試行してください。
• 実行の開始はむやみに再試行しないでください。 ツールやブラウザの実行の開始がタイムアウトした場合は、別の実行を開始する前に GET /v1/tools/runs を確認してください。再試行と冪等性を参照してください。

OpenAI と Anthropic の公式 SDK は、429 と 5xx をすでにバックオフ付きで 2 回再試行します。この回数を変えるには、クライアントに max_retries（Python）または maxRetries（Node.js）を渡します。素の HTTP 呼び出しには、次のようなヘルパーを使ってください。

import os
import random
import time

import requests

RETRYABLE = {429, 500, 502, 503, 504}


def backoff(attempt, retry_after=None):
    if retry_after:
        return float(retry_after)
    return min(30, 2 ** (attempt - 1)) + random.random()


def post_with_retry(url, payload, max_attempts=5):
    headers = {"Authorization": f"Bearer {os.environ['LOVELY_API_KEY']}"}
    for attempt in range(1, max_attempts + 1):
        try:
            r = requests.post(url, json=payload, headers=headers, timeout=300)
        except (requests.ConnectionError, requests.Timeout):
            if attempt == max_attempts:
                raise
            time.sleep(backoff(attempt))
            continue
        if r.status_code in RETRYABLE and attempt < max_attempts:
            time.sleep(backoff(attempt, r.headers.get("retry-after")))
            continue
        if not r.ok:  # other 4xx, or still failing after the last attempt
            raise RuntimeError(f"{r.status_code}: {r.text[:500]}")
        return r.json()


reply = post_with_retry(
    "https://lovelyrouter.com/v1/chat/completions",
    {"model": "gpt-6.1-sol", "messages": [{"role": "user", "content": "Hello"}]},
)
print(reply["choices"][0]["message"]["content"])

Anthropic、OpenAI、Gemini、Lovely Router 独自のどのエラー形式にも、人が読むための error.message があります。ステータスコードと x-lovely-request-id ヘッダーとあわせてログに記録してください。