エラーと復旧

クライアント応答、ルート検査、リクエストログのエラー情報と、再試行・復旧・設定変更の判断方法をまとめます。

3 種類の情報を区別する§

1 回の失敗に 3 種類のコードが現れる場合があります。用途はそれぞれ異なります。

項目	表示場所	用途
code	クライアント HTTP 応答	今回のリクエストが失敗した理由を呼び出し元へ伝えます
error_code	リクエストログと試行チェーン	アップストリームの失敗を正規化し、絞り込みと診断に使います
reason_code	ルーティングチェック	AccessKey、Group、認証情報が候補になれない理由を説明します

3 種類のコードを相互に置き換えないでください

ルート検査には no_available_group、実際のリクエストには no_available_candidate、最後のアップストリーム試行のログには upstream_client_error が現れる場合があります。自動化処理は、呼び出しているインターフェース自身の項目を読んでください。

message を解析しないでください

管理 API の message はローカライズされ、アップストリームのメッセージも変わる可能性があります。プログラムの判断には code と構造化された data を使い、message と error_summary は人による確認だけに使ってください。

管理 API エラー§

管理 API のエラーコードは大文字のスネークケースです。応答構造、認証、主要リソースは管理 API を参照してください。

共通・認証・リソース

エラーコード	HTTP	意味	対処方法
BAD_REQUEST	400	リクエストパラメーターまたはパスが不正です	リクエストを修正して再試行します
INVALID_JSON	400	JSON の形式、項目、または本文構造が不正です	エンドポイント仕様に合わせて JSON を修正します
VALIDATION_FAILED	400	解析には成功しましたが、業務検証に失敗しました	data の項目位置情報を確認します
REQUEST_TOO_LARGE	413	管理リクエスト本文がサイズ上限を超えています	本文を小さくするか、操作を分割します
UNAUTHORIZED	401	管理認証情報が無効です	AUTH_KEY または AccessKey を確認します
FORBIDDEN	403	現在の主体にはこの操作の権限がありません	AUTH_KEY を使うか、操作範囲を縮小します
AUTH_LOCKED	429	同じ直接接続元で認証失敗が続き、一時的にロックされました	Retry-After に従って待機し、誤ったキーの再試行を止めます
NOT_FOUND	404	対象リソースが存在しません	リソース一覧を更新し、ID を確認します
ROUTE_NOT_FOUND	404	要求された管理ルートが存在しないか、廃止されています	パスを現在のバージョンのルート契約と照合してください
METHOD_NOT_ALLOWED	405	管理ルートは存在しますが、HTTP メソッドがサポートされていません	そのルートで宣言されたメソッドを使用してください
DUPLICATE_RESOURCE	409	一意なリソースがすでに存在します	既存リソースを使うか、一意項目を変更します
BAD_GATEWAY	502	管理操作が依存するアップストリーム要求に失敗しました	data とアップストリーム状態を確認してから再試行します
DATABASE_ERROR	500	データベース操作に失敗しました	サービスログとデータベースの可用性を確認します
INTERNAL_SERVER_ERROR	500	分類されていない内部エラーです	サービスログで診断し、書き込み操作を無条件に再実行しないでください

冪等性・並行更新・実行時復旧

エラーコード	HTTP	意味	対処方法
IDEMPOTENCY_KEY_REQUIRED	428	この書き込み操作には Idempotency-Key が必要です	正規 UUID v4 を生成してリクエストに付けます
INVALID_IDEMPOTENCY_KEY	400	Idempotency-Key が正規の小文字 UUID v4 ではありません	正規 UUID v4 に置き換えます
IDEMPOTENCY_KEY_REUSED	409	同じ冪等キーが別のリクエストに使われました	新しい論理操作には新しいキーを生成します
IDEMPOTENCY_RESULT_EXPIRED	410	冪等結果の保持期限は切れましたが、操作の識別情報は残っています	data で完了済みリソースを確認し、そのまま再作成しないでください
CONTROL_OPERATION_INCOMPLETE	503	データベースへのコミット後、実行時復旧がまだ完了していません	同じ冪等キーを保持し、自動調整を待ちます
CONTROL_RECOVERY_PENDING	503	先にコミットされた操作がまだ復旧中です	data.retry_after_ms に従って待機してから再試行します
SETTINGS_PRECONDITION_REQUIRED	428	設定更新に If-Match がありません	設定と ETag を読み、If-Match を付けて更新します
SETTINGS_VERSION_CONFLICT	412	読み取り後に別のリクエストが設定を変更しました	data の現在設定を使って再度マージします

Group・モデル・サブスクリプション認証情報

エラーコード	HTTP	意味	対処方法
GROUP_IN_USE	409	Group がまだ AccessKey から参照されています	data に記載された参照を先に解除します
INVALID_CREDENTIAL_STATE	409	現在の状態では認証情報を復帰できません	認証情報の状態を更新し、許可された操作を選びます
CHANNEL_TARGET_CONFLICT	409	別の Group が同じチャネルターゲットを使用しています	既存 Group を使うか、重複ターゲットを明示的に確認します
MODEL_NAME_CONFLICT	409	同じ Group 内でクライアント向けモデル名が競合しています	data.conflicts に従ってモデル名または別名を修正します
NO_ACTIVE_CREDENTIAL	409	Group に操作を実行できる認証情報がありません	認証情報を追加、有効化、または再認可します
MODEL_PRICE_UNPRICED_CONFIRMATION_REQUIRED	409	モデルを価格未設定にするには明示的な確認が必要です	確認して再送信します
MODEL_PRICE_REFERENCED	409	モデル価格がまだ Group から参照されています	参照を解除してから価格を削除します
MODEL_PRICE_AUTOMATIC_DELETE_FORBIDDEN	409	自動同期されたモデル価格は手動削除できません	同期元を変更するか、次回同期を待ちます
OAUTH_FILE_INVALID	400	OAuth JSON を認識できないか、項目が無効です	再エクスポートした完全なファイルをインポートします
OAUTH_FILE_TOO_LARGE	413	OAuth ファイルがサイズ上限を超えています	必要な認証情報だけを残します
AUTHORIZATION_UNAVAILABLE	503	ブラウザ認可、デバイスコード認可、またはサブスクリプション認証情報の更新が一時的に利用できません	チャネル機能、ネットワーク、サービスログを確認してください
AUTHORIZATION_STATE_INVALID	400	認可コールバックの state が無効または不一致です	認可を新しく開始します
AUTHORIZATION_EXCHANGE_FAILED	502	認可コードから認証情報への交換に失敗しました	アップストリーム状態を確認して再認可します
STAGED_CREDENTIAL_NOT_READY	409	ステージ済み認証情報の認可が完了していません	認可を完了してから接続します
STAGED_CREDENTIAL_EXPIRED	410	ステージ済み認証情報の期限が切れました	再インポートまたは再認可します
STAGED_CREDENTIAL_CONSUMED	409	ステージ済み認証情報は使用済みです	一覧を更新し、再接続しないでください
STAGED_CREDENTIAL_MISMATCH	409	ステージ済み認証情報が対象 Group と一致しません	一致するチャネルと Group を選びます
DUPLICATE_CREDENTIAL_IDENTITY	409	同じサブスクリプションアカウントが Group に存在します	既存アカウントを使うか、別の Group に接続します
CREDENTIAL_REAUTHORIZATION_REQUIRED	409	認証情報の再認可が必要です	OAuth 認可をやり直します
CREDENTIAL_AUTH_OUTCOME_UNKNOWN	409	認可結果を確認できません	状態を更新し、すぐに認可を繰り返さないでください
CREDENTIAL_REFRESH_TEMPORARILY_UNAVAILABLE	503	認証情報を一時的に更新できません	後で再試行するか、別の認証情報を使います
CREDENTIAL_VERSION_CONFLICT	409	操作中に認証情報が変更されました	認証情報を更新して操作をやり直します
RESET_CREDIT_UNAVAILABLE	409	現在利用できるクォータリセット枠がありません	アップストリームが新しいリセット機会を提供するまで待ちます
RESET_CREDIT_REJECTED	502	アップストリームがクォータリセットを拒否しました	アカウント状態を確認し、アップストリームへ連絡します
RESET_CREDIT_OUTCOME_UNKNOWN	503	クォータリセット結果を確認できません	同じ Idempotency-Key で再試行します

data はエラー契約の一部です

呼び出し元の判断に必要な場合だけ data を返します。競合リソース、項目位置、現在設定と ETag、操作 ID、失敗段階、再試行時刻、クォータ詳細などが含まれます。構造が宣言されていないエラーでは通常 data を返しません。

管理エラーの構造化 data

次の表には安定した構造を持つ管理エラーだけを示します。同じエラーコードでも別の状況では data が付かない場合があります。

エラーコード	data フィールド	返される状況
VALIDATION_FAILED	entry, field, reason_code	一部の認証情報フィールド検証が失敗したとき
AUTH_LOCKED	retry_after_seconds	認証がロックされたとき。Retry-After ヘッダーも返されます
BAD_GATEWAY	trigger, checked_at_ms, successful_fetch_at_ms, not_modified, skipped, error_code	Models.dev の手動同期が失敗したとき
IDEMPOTENCY_KEY_REUSED	operation_id, operation_kind	冪等キーが別のリクエストに対応しているとき
IDEMPOTENCY_RESULT_EXPIRED	operation_id, operation_kind, resource_identity, completed_at_ms	冪等結果が圧縮済みのとき
CONTROL_OPERATION_INCOMPLETE	operation_id, operation_kind, last_completed_stage, failed_stage, can_reconcile	データベースのコミット後も実行状態の復旧が完了していないとき
CONTROL_RECOVERY_PENDING	operation_id, operation_kind, failed_stage, retry_after_ms	先にコミットされた操作が現在の書き込みを妨げているとき
SETTINGS_VERSION_CONFLICT	settings, settings_etag	If-Match の値が古いとき
GROUP_IN_USE	access_keys[] { id, name }	AccessKey から参照中の Group を削除するとき
CHANNEL_TARGET_CONFLICT	groups[] { id, name }	確認なしで同一チャネルターゲットを作成するとき
MODEL_NAME_CONFLICT	conflicts[] { client_model, indexes }	Group 内のモデル名またはエイリアスが競合するとき
MODEL_PRICE_UNPRICED_CONFIRMATION_REQUIRED	id	確認なしですべての価格を null にするとき
MODEL_PRICE_REFERENCED	id, reference_count, reference_group_count	Group から参照中の価格を削除するとき
MODEL_PRICE_AUTOMATIC_DELETE_FORBIDDEN	id	自動同期された価格を削除するとき

データプレーンエラー§

GPT-Load が生成するデータプレーンエラーは小文字のスネークケースで、基本構造は { "code": "...", "message": "..." } です。コスト上限エラーでは構造化された error と data も返します。

エラーコード	HTTP	意味	対処方法
invalid_access_key	401	AccessKey が存在しない、無効、期限切れ、または送信元が許可されていません	クライアントの AccessKey を確認します。この失敗はリクエストログに記録されません
protocol_endpoint_not_found	404	パスが有効なデータプレーンエンドポイントではありません	ベース URL、プロトコル、パスを確認します
method_not_allowed	405	エンドポイントは存在しますが、HTTP メソッドが未対応です	エンドポイントで宣言されたメソッドを使います
invalid_protocol_request	400	リクエスト本文またはプロトコル項目を解析できません	クライアントプロトコルに合わせて修正します
model_required_by_filter	400	AccessKey にモデル制限がありますが、リクエストにモデル名がありません	モデルを指定するか、モデル制限を外します
no_available_candidate	503	現在ルーティング可能な Group または認証情報がありません	ルート検査で具体的な reason_code を確認します
upstream_connect_failed	502	利用可能なアップストリームへ接続できません	ネットワーク、プロキシ、アップストリームアドレスを確認します
upstream_timeout	504	アップストリーム要求がタイムアウトしました	リクエストログの送信・コミット状態を確認し、非冪等要求を無条件に再実行しないでください
upstream_protocol_error	502	アップストリーム応答を安全に処理できません	応答形式、Content-Encoding、サービスログを確認します
protocol_conversion_unsupported	422	ネイティブ実行または安全な変換が可能なルートがありません	プロトコル、Operation、またはチャネルを変更します
request_too_large	413	データプレーン要求本文がサイズ上限を超えています	リクエスト本文を小さくします
unsupported_content_encoding	415	未対応の Content-Encoding が使われています	identity、gzip、br、deflate、または zstd を使用してください
invalid_content_encoding	400	圧縮された要求本文をデコードできません	本文を再エンコードし、ヘッダーを確認します
not_acceptable	406	クライアントが identity 応答を受け入れません	identity 応答を許可します
model_list_too_large	500	表示可能なモデル一覧が安全な応答上限を超えています	AccessKey から見えるモデル範囲を縮小します
access_key_rate_limited	429	AccessKey が RPM 上限を超えました	Retry-After に従って待機します
access_key_cost_limit_exceeded	429	AccessKey が推定コスト上限に達しました	data.recoverable、next_available_at_ms、blocking_rules を確認します
configuration_changed	503	リクエストが使った設定スナップショットは古くなっています	Retry-After に従って短時間待ち、再試行します

access_key_cost_limit_exceeded の error には type、code、message と省略可能な Unix 秒の resets_at が含まれます。data には recoverable、Unix ミリ秒の next_available_at_ms、blocking_rules が含まれます。各ブロックルールには id、kind、limit_usd、used_usd があり、周期ルールには period_seconds と window_ends_at_ms も含まれます。

アップストリームエラーは別の構造になる場合があります

ネイティブルートは秘匿化と安全確認後のアップストリームエラー本文を返し、変換ルートはクライアントプロトコルのエラー構造へ投影します。OpenAI、Anthropic、Gemini で項目が異なるため、すべての失敗が code と message だけとは限りません。

リクエストログエラー§

最上位の error_code はリクエスト全体の最終結果、attempts[].error_code は 1 回のアップストリーム試行を表します。再試行後に成功した場合、最上位にエラーがなくても前の試行にはエラーコードが残ります。

次の表はリクエストログだけで追加使用する正規化コードを示します。データプレーン固定エラーと同名のコードは前節を参照し、重複掲載しません。

エラーコード	意味	対処方法
upstream_rate_limited	アップストリームが今回の試行をレート制限しました	Retry-After、クールダウン、後続試行を確認します
upstream_model_unavailable	アップストリームモデルまたは候補が利用できません	モデル設定と後続候補を確認します
upstream_invalid_key	アップストリームがチャネル認証情報を拒否しました	認証情報を更新し、失敗蓄積やブラックリストを確認します
upstream_authentication_required	サブスクリプション認証情報の更新または再認可が必要です	再試行判断を確認し、再認可します
upstream_host_error	アップストリームがサーバーエラーを返しました	Group がスキップされたか、実際に再試行したか確認します
upstream_client_error	アップストリームがリクエスト自体を不正と判断しました	エラー要約とパラメーターを確認します。通常、認証情報を替える再試行は不適切です
upstream_error	これ以上分類できないアップストリーム失敗です	状態コード、要約、該当ルールを合わせて判断します
upstream_sse_error	アップストリームが SSE イベントでエラーを報告しました	ストリームのコミット状態を確認します。出力開始後は再試行できません
upstream_stream_terminated	アップストリームストリームが完了前に切断されました	ネットワークとストリームアイドルタイムアウトを確認します
upstream_stream_idle_timeout	アップストリームストリームから長時間データがありません	アイドルタイムアウトを調整するか、アップストリームを確認します
upstream_response_incomplete	アップストリームが未完了状態を明示しました	エラー要約とアップストリーム Request ID を確認します
downstream_write_failed	クライアントへの応答書き込みに失敗しました	クライアント切断、リバースプロキシ、ネットワークを確認します
client_canceled	クライアントがリクエストをキャンセルしました	通常は対処不要です
server_shutdown	サービス終了時にリクエストがキャンセルされました	サービス復旧後、呼び出し元が再試行を判断します
internal_error	分類可能な通常結果を生成できませんでした	同じ Request ID のサービスログを確認します
credential_decrypt_failed	候補認証情報を復号できません	一致する ENCRYPTION_KEY を復元するか、認証情報を再登録します
credential_normalization_failed	候補認証情報を実行形式へ正規化できません	有効な認証情報を再登録します
credential_proxy_prepare_failed	認証情報レベルのプロキシを初期化できません	この認証情報のプロキシ設定を修正します
group_proxy_prepare_failed	Group レベルのプロキシを初期化できません	Group のプロキシ設定を修正します
server_is_overloaded	アップストリームが過負荷を明示しました	再実行の安全性と後続候補を確認します
rate_limit_exceeded	アップストリームが容量制限を明示しました	クールダウンと後続候補を確認します

リクエストログには安全な要約を保存します

error_summary は秘匿化され長さも制限されます。元のエラー本文はログに保存しません。AccessKey 認証失敗は RequestLog 作成前に起きるため、invalid_access_key を返し、頻度制限されたセキュリティイベントだけを記録します。

リクエストログ項目§

リクエスト最上位

項目	値	解釈
request_id	UUID v4	リクエスト詳細とサービスログを関連付ける GPT-Load リクエスト ID
status	success / error / incomplete / canceled	リクエスト全体の最終状態
status_code	0 / HTTP ステータス	リクエスト全体の最終ステータスです。HTTP 応答が生成されなかった場合は 0 になります
error_code	正規化エラーコード	絞り込みと集計に使います。error_summary から逆算しないでください
error_summary	秘匿化され、長さを制限した要約	人による診断用で、アップストリーム原文の保持は保証しません
attempt_count	0 以上の整数	実際に記録されたアップストリームまたはローカル実行試行の数

`attempts[]` 内の試行フィールド

項目	値	解釈
sequence	1 から始まる整数	このリクエスト内での試行順序
status_code	0 / HTTP ステータス	この試行の結果ステータスです。アップストリームが応答しなかった場合は 0 になります
error_code	正規化エラーコード	この試行の失敗理由です。成功時は空文字列です
error_summary	秘匿化され、長さを制限した要約	人によるトラブルシューティング専用
failure_category	ok / rate_limited / model_unavailable / invalid_key / upstream_host_error / client_error / conversion_unsupported / downstream_cancel / authentication_required / ambiguous	安定した業務分類です。成功した試行は ok です
failure_origin	client / upstream / downstream / internal / null	エラーの責任領域です。古いレコードは null の場合があります
failure_scope	request / model / credential / group / null	エラーが影響する最小リソース範囲です。非該当または古いレコードは null です
retry_directive	none / refresh_credential / next_candidate / null	Judge が決定した再試行意図です。古いレコードは null の場合があります
effect	none / cooldown_credential / record_credential_failure / skip_group / null	この試行が実行状態に与える唯一の効果です。古いレコードは null の場合があります
rule_id	安定したルール識別子 / null	決定を生成したルールです。古いレコードは null の場合があります
will_retry	true / false	その後、別のアップストリーム試行が実際に始まったか
dispatch_state	not_sent / maybe_sent / local / null	未送信、アップストリーム到達の可能性あり、GPT-Load 内で完結、または古いレコードで不明のいずれかです
response_started	true / false	この試行で応答が生成されたかを示します。local でも true になる場合があります
committed	true / false	クライアント出力を開始したか。コミット後は候補を安全に切り替えられません
upstream_request_id	アップストリームリクエスト ID / null	アップストリームへの問い合わせに使用します。ローカル実行または ID が返らなかった場合は null です
action	terminate / retry / cooldown_credential / fail_credential / skip_group	互換表示項目です。正確な判断には retry_directive と effect を使います

完全な例§

リクエストログ内の 1 回の失敗試行

status_code: 400
error_code: upstream_client_error
failure_category: client_error
failure_origin: upstream
failure_scope: request
retry_directive: none
effect: none
rule_id: fallback.http_client_error
will_retry: false
response_started: true
committed: false

アップストリームが 400 を返し、問題は今回のリクエストだけに影響すると判断されています。ゲートウェイは認証情報を替えて再試行せず、クールダウン、ブラックリスト、Group のスキップも行いません。秘匿化された要約とクライアントパラメーターを確認してください。

ルート検査の理由コード§

ルート検査は現在の設定と実行状態を読み取り専用でシミュレーションします。アップストリーム要求、Token 消費、認証情報のロック、リクエストログ書き込みは行いません。最上位の理由は全体、Group と認証情報の行は詳細な理由を示します。

原因コード	階層	意味	対処方法
access_key_disabled	AccessKey	AccessKeyが無効化されている	AccessKeyのページで有効化する
access_key_expired	AccessKey	AccessKeyの有効期限が切れています	新しいキーを作成するか、有効期限を延長する
protocol_filtered	AccessKey	このキーではこのプロトコルが選択されていません	キーで対応するプロトコルを追加選択
model_filtered	AccessKey	リクエストされたモデルが許可範囲外である	キーのモデル制限をチェック
model_required_by_filter	AccessKey	キーがモデルを制限しているが、リクエストにモデル名がない	リクエストでモデルを明示するか、キーのモデル制限を外してください
operation_unsupported	リクエスト	現在のプロトコルでこの Operation をサポートするチャネルがありません	この機能をサポートする Group を使います
no_route_target	リクエスト	このモデルまたは Operation のルートターゲットがありません	少なくとも 1 つの Group でモデルが公開されていることを確認します
no_available_group	リクエスト	ルートターゲットはありますが、利用可能な Group がありません	各 Group の reason_code を確認します
native_route_required	Group	リクエストがネイティブルートを要求しているが、この Group は変換でしか提供できない	クライアントと同じプロトコルの Group を使ってください
group_disabled	Group	Groupが無効化されています	このGroupを有効化してください
group_filtered	Group	このGroupはこのAccessKeyの認可範囲に含まれていません	キーにそのGroupを追加してください
no_credentials	Group	Groupに認証情報がありません	Groupに認証情報を追加してください
group_weight_zero	Group	旧設定の Group の重みが 0 になっている	自動の重み、または 1～100 の手動の重みに変更する
no_available_credential	Group	Group 内の全認証情報が利用できません	認証情報レベルの reason_code を確認します
credential_disabled	認証情報	認証情報が無効化されています	有効化するか、別の認証情報を使用してください
credential_auth_unavailable	認証情報	サブスクリプションアカウントの認可が期限切れです	再認可してください。サブスクリプションアカウントページを参照してください
credential_blacklisted	認証情報	認証情報がブラックリストに登録されています	認証情報の有効性を確認して復帰します
credential_cooldown	認証情報	認証情報がクールダウン中です	自動復帰を待つか、認証情報を追加して負荷を分散してください
credential_weight_zero	認証情報	旧構成に残った認証情報の重み 0	自動の重み、または 1～100 の手動の重みに変更する

内部の除外理由は現在のルート検査では返されません

スケジューラは、実際のリクエスト候補をリクエスト開始時に取得した認証情報集合へ制限するために credential_not_allowed も定義しています。現在の /api/route/inspect はこのリクエスト単位の認証情報集合を受け取らないため、この理由コードを返しません。

設定変更後にルート検査を再実行すれば、実際のモデル要求を送らずに現在状態を確認できます。

再試行と復旧§

リクエストエラー——リクエストを修正し、認証情報の切り替えや健全性変更は行いません。
レート制限——Retry-After に従います。認証情報単位の制限では通常クールダウンし、別候補を試します。
無効な認証情報——認証情報の失敗を記録し、連続失敗がしきい値に達するとブラックリストに入れます。
アップストリームホストエラー——現在の Group をスキップします。読み取り専用操作か、処理前の拒否が明示された場合だけ安全に再実行できます。
ストリーミング応答——クライアント出力開始後は候補を切り替えず、重複や不整合を防ぎます。
結果不明の管理書き込み——元の Idempotency-Key を保持・再利用し、先に操作状態を確認します。

スケジューリング、クールダウン、ブラックリストの完全な仕組みを見る →