Gateway のエラーコード
Gateway の /v1 エンドポイントが返すすべてのエラーコードと、その HTTP ステータス、再試行で解決するかどうか、対処法です。
コードの場所#
各エンドポイントはそれぞれのプロトコルのエラー形式で応答するので、公式 SDK がそのまま読み取れます。
/v1/chat/completionsと/v1/responses：{"error": {"message", "type", "param", "code"}}。コードはerror.codeにあります。/v1/messagesと/v1/messages/count_tokens：{"type": "error", "error": {"type", "message"}}。コードはメッセージそのものです。ただし 429 の場合は読みやすいメッセージが入り、コードはerror.codeにあります。/v1/modelsは、問い合わせたクライアントの形式で応答します。リクエストがanthropic-versionかx-api-keyを送っていれば Anthropic の形式、それ以外は OpenAI の形式です。
プロバイダー自身が書いた拒否（リクエストの内容に関する 400、413、422）は、プロバイダーの文面のまま渡され、Gateway のコードは付きません。
再試行のヘッダー：Retry-After は何秒待つかを示します。X-Should-Retry: false は、OpenAI と Anthropic の SDK に再試行しないよう伝えます。
Gateway 側の問題か#
5xx エラーが返る、またはまったく応答がない場合は、Gateway のステータスページ（英語）を開きます。ログインなしで、私たちがホストする Gateway が準備完了かどうかをブラウザーから確認し、結果ごとの対処法を示します。
一覧#
| コード | ステータス | 再試行 | 対処 |
|---|---|---|---|
application_key_required | 401 | 不可 | キーを Authorization: Bearer <key> として送ります（/v1/chat/completions 以外では x-api-key でも可）。 |
application_key_not_accepted | 401 | 不可 | キーが取り消された、期限切れ、入力ミス、または許可リスト外のアドレスから使われています。キーの一覧で確認するか、新しいキーを作成します。 |
gateway_key_attempts_exceeded | 429 | Retry-After のあと | あなたのアドレスから、受け付けられないキーが多数送られました。ツールが送るキーを修正してから待ちます。 |
gateway_key_model_not_allowed | 403 | 不可 | キーの許可するモデルにこのモデルが含まれていません。一覧のモデルか auto を使うか、キーの許可リストを変更します。 |
server_application_required | 403 | 不可 | リクエストがブラウザから送られた（Origin ヘッダー）か、想定外のクエリ文字列がありました。Gateway はサーバー、CLI、スクリプトから呼び出します。 |
inference_not_admitted | 403 | 不可 | このワークスペースは現在 Gateway を使えないか、選ばれたモデルを使えません。AI Gateway のページから利用を申請してください。 |
model_not_enabled | 403 | 不可 | ワークスペースのモデル設定でこのモデルが除外されています。他のモデルか auto を使うか、オーナーまたは管理者に許可を依頼します。 |
model_not_found | 404, 400 | 不可 | モデルが不明か、このエンドポイントで許可されたモデルのどれもリクエストを処理できません。GET /v1/models の名前か auto を使います。 |
video_not_found | 404 | 不可 | この API キーではこの id の動画は作成されていません。動画は作成したキーでのみ読み取れます。 |
invalid_model | 400 | 不可 | agentlab/… という名前はモデルではありません。auto か GET /v1/models の名前を使います。 |
invalid_provider | 400 | 不可 | provider.only にプロバイダーではない名前がある、指定したモデルを除外している、または一覧のプロバイダーにリクエストを処理できるモデルがありません（error.param は provider.only）。一覧を直します。メッセージに有効なプロバイダーが示されます。 |
unsupported_parameter | 400 | 不可 | Gateway が受け付けない OpenAI のフィールドが含まれています（error.param がそのフィールド）。そのフィールドを外します。 |
prompt_reference_invalid | 400 | 不可 | /v1/prompts/{prompt}/completions ではプロンプトを id または slug で指定します。末尾に @<バージョン> を付けられます。 |
prompt_not_found | 404 | 不可 | キーのワークスペースにその名前のプロンプトまたはバージョンがありません。そのワークスペースの「プロンプト」タブを確認してください。 |
prompt_variables_mismatch | 400 | 不可 | variables はプロンプトの変数とちょうど一致する必要があります。メッセージに不足している変数と使われない変数が示されます。 |
prompt_variables_invalid | 400 | 不可 | variables は値がすべて文字列のオブジェクトにしてください。 |
prompt_messages_not_accepted | 400 | 不可 | プロンプトの呼び出しでは messages ではなく variables を送ります。メッセージはプロンプトが持っています。 |
prompt_too_large | 400 | 不可 | 変数を埋めたプロンプトがリクエストの上限を超えています。値を短くしてください。 |
invalid_inference_request | 400 | 不可 | Chat Completions の本文に、Gateway が受け付けないフィールドまたは値があります。API リファレンスを参照してください。 |
invalid_request | 400 | 不可 | Responses の本文が保存済みの状態（previous_response_id、conversation、prompt）または拒否されるツールを求めています。param にフィールド名が入ります。 |
request_key_invalid | 400 | 不可 | Idempotency-Key は 1 回まで、8～128 文字で送る必要があります。 |
request_key_already_used | 409 | 不可 | この Idempotency-Key はすでに使われています。新しいリクエストには新しいキーを送ります。 |
routing_header_invalid | 400 | 不可 | X-AgentLab-Routing は正確に auto とし、1 回だけ送ります。 |
invalid_metadata | 400 | 不可 | X-AgentLab-Metadata または本文の metadata のタグを記録できません。メッセージがどの規則に反したかを示します。文字列値が最大 16 個の JSON オブジェクトを 1 つ送ります。キーは英数字・_・.・- の 1〜64 文字、値は 1〜512 文字です。タグを参照。 |
json_required | 415 | 不可 | Content-Type: application/json を送ります。 |
request_too_large | 413 | 不可 | 本文がエンドポイントの受け付けるサイズを超えています。Chat Completions、音声生成、画像生成は 1 MiB、Messages と Responses は 32 MiB、文字起こしは 26 MiB（音声ファイルは 25 MiB まで）、画像編集と動画は 64 MiB です。 |
request_body_unreadable | 400 | 可 | リクエスト本文が宣言した長さに達する前に途切れたか、時間内に届きませんでした。リクエストを送り直します。 |
gateway_guardrail_blocked | 400 | 不可 | ワークスペースのガードレールがブロック対象（カード番号、API キー、登録済みの語句など）を見つけました。メッセージにチェック名が含まれます。その内容を削除するか、ワークスペース管理者に AI Gateway › はじめに でガードレールを変更してもらいます。 |
inference_allowance_exceeded | 429 | 不可 | 月間上限、部門の上限、またはローリングウィンドウに余裕がありません。メッセージにどの上限かが書かれます。引き上げるか、リセットを待ちます。 Free プランではプランに含まれるリクエスト数やモデル使用料（gateway_plan_requests、gateway_plan_spend）、従量課金（前払い）ではクレジット残高（gateway_balance）の場合もあります。AI Gateway › プラン でクレジットを追加すると、同じキーですぐに使えます。 |
gateway_rate_limited | 429 | Retry-After のあと | このキーまたはワークスペースが、レート制限を超える 1 分あたりのリクエスト数またはトークン数を送りました。または、Gateway が同時に処理できる音声・画像・動画のリクエスト数に達しています。待つか、制限を引き上げます。 |
provider_rate_limited | 429 | Retry-After のあと | モデルプロバイダーが混み合っています。SDK が自動で待ってから再試行します。 |
count_tokens_concurrency_exceeded | 429 | Retry-After のあと | トークン数を数えるリクエストが同時に多すぎます。1 秒ほどしてから再試行します。 |
provider_overloaded | 529 | 可 | モデルプロバイダーが過負荷です。少し待って再試行するか、auto または他のモデルを使います。 |
inference_failed | 502 | 可（1 回） | プロバイダーが応答できませんでした。失敗が続く場合は、AI Gateway › 使用量 でそのリクエストを開きます。 |
settlement_pending | 503 | 不可 | モデルは応答しましたが、使用量をまだ記録できなかったため、応答を保留しました。再送しないでください。自動的に確定します。 |
inference_unavailable | 503 | 可 | Gateway が判断に必要なものに接続できませんでした。少し待って再試行します。 |
gateway_unavailable | 503 | 可 | Gateway サーバーが起動中か、設定を再読み込みしています。少し待って再試行します。 |
gateway_not_configured | 503 | 不可 | このサーバーには Gateway が設定されていません。セルフホストの Gateway なら、デプロイの設定を確認します。 |
transport_deadline_unavailable | 503 | 可 | サーバーが接続の制限時間を設定できませんでした。再試行します。 |
この表はビルドのたびに Gateway のコードと照合されます。Gateway が返しうるコードがこの表にないと、ビルドは失敗します。