よくあるエラー

エラー本文の形式

モデルエンドポイントのエラーは JSON で返されます。

{
  "error": {
    "message": "Insufficient user quota, remaining: ＄0.000000 (request id: 202610230158421013999388268d9d615)",
    "type": "error",
    "code": "insufficient_user_quota"
  }
}

• message は人が読むための説明で、末尾に (request id: <id>) が付きます。同じ id はレスポンスヘッダー X-Oneapi-Request-Id にも含まれます。サポートに問い合わせる際は必ず添えてください。
• code は機械可読なエラーコードです。エラーによっては空文字列になるため、その場合は HTTP ステータスコードで判断してください。
• message はユーザーの言語設定または Accept-Language に応じて翻訳され、内容も変更され得ます。プログラム側の判定には HTTP ステータスコードと code を使ってください。

Claude Messages（/v1/messages）は代わりに {"type": "error", "error": {"type": "...", "message": "..."}} を返します。非同期タスクのエンドポイント（/v1/video/generations、/v1/videos、/suno/*）は、ルーティング後に発生したエラーを {"code", "message", "data"} で返し、その message に request id は含まれません。

401 Unauthorized

API Key が無い、無効、期限切れ、無効化済み、またはクォータを使い切っています。

• Authorization ヘッダーが無い、または Bearer sk-... の形式になっていない。
• Key が削除、無効化、または期限切れになっている。
• Key の残りクォータが 0 になっている。
• モデルエンドポイントに Management Key（rat_...）を送っている。モデル呼び出しには sk- で始まる API Key が必要です。

必要ならコンソールの API Keys ページで新しい Key を作成してください。Key のクォータと有効期限は残高とクォータを参照してください。

403 Forbidden

403 にはまったく異なる 2 つの原因があります。まずレスポンスの code を確認してください。

残高または Key クォータの不足

• insufficient_user_quota：アカウント残高がこのリクエストの見積額を支払えない、またはサブスクリプションのクォータが残っていない。
• pre_consume_token_quota_failed：Key の残りクォータがこのリクエストの見積額を支払えない。

チャージする、Key のクォータを上げる、または max_tokens を下げて見積額をクォータ内に収めてください。詳しくは残高とクォータを参照してください。

権限の不足

これらは通常 code が空です。どのチェックで失敗したかはメッセージで判断してください。

• Key のモデル制限にこのモデルが含まれていない（This token has no access to model ...）。
• Key のグループがアカウントで利用できない。
• 送信元 IP が Key の IP 許可リストに無い（code は access_denied）。
• アカウントが無効化されている。

429 Too Many Requests

リクエスト頻度の制限に達しています。制限はアカウント単位で、同じアカウントのすべての Key が枠を共有します。Key を増やしても上限は上がりません。拒否されたリクエストは課金されません。

• ランダムなジッターを付けた指数バックオフで再試行します。
• 同時実行数を下げるか、リクエストをより長い時間に分散します。
• 429 のレスポンス本文が空の場合があります。メッセージではなくステータスコードで判断してください。

モデルリクエストの制限と上流 429 の再試行方法は利用量と請求を参照してください。

503 モデルが利用できない

• code が model_not_found で、メッセージが “No valid upstream service” のような場合：現在、あなたのグループに対してこのモデルを提供するチャネルがありません。モデル ID の綴りと、そのモデルがアカウントで利用可能かを確認してください。同じリクエストをすぐ再試行しても通常は解決しません。

502 / 503 上流エラー

• モデルプロバイダーが返した 502 などの 5xx は、すべての再試行が失敗した後にそのまま返されます。
• code が get_channel_failed、メッセージが “Upstream service is temporarily unavailable” の場合：チャネル背後の上流アカウントが利用できません（残高や認証情報の失効など）。RouteAPI は可能なら別チャネルで再試行し、それでも失敗するとこの汎用メッセージを返して内部アラートを発報し、故障したチャネルを自動で無効化することがあります。時間をおいて再試行してください。
• code が client_failfast（503）：同じ API Key のこのモデルへのリクエストが高い割合で失敗し続けたため、その Key とモデルの組み合わせに短時間の保護が働いています。レスポンスには Retry-After と X-Client-Failfast: 1 が付きます。待ってから再試行し、その前に失敗原因を修正してください。

一時的なエラーは時間をおいて再試行してください。解消しない場合は request id を添えてサポートに連絡してください。