Crescendo Lab ドキュメント
日本語
無料で始める

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 の形式です。

どのエラーオブジェクトにも、誰の失敗かを示す origin(gateway、provider、model、guardrail、routing_rule)が含まれます。ヘッダー送信前のエラー応答には同じ値が X-Agentlab-Error-Origin にも入るので、誰に問い合わせればよいかがわかります。コードとステータスは変わりません。開始済みのストリーム内のエラーは、エラーイベントに origin を含みます。

プロバイダー自身が書いた拒否(リクエストの内容に関する 400、413、422)は、プロバイダーの文面のまま渡され、Gateway のコードは付きません。

再試行のヘッダー:Retry-After は何秒待つかを示します。X-Should-Retry: false は、OpenAI と Anthropic の SDK に再試行しないよう伝えます。

Gateway 側の問題か#

5xx エラーが返る、またはまったく応答がない場合は、Gateway のステータスページ(英語)を開きます。ログインなしで、私たちがホストする Gateway が準備完了かどうかをブラウザーから確認し、結果ごとの対処法を示します。

一覧#

コードステータス発生元再試行対処
application_key_required401gateway不可キーを Authorization: Bearer <key> として送ります(/v1/chat/completions 以外では x-api-key でも可)。
application_key_not_accepted401gateway不可キーが取り消された、期限切れ、入力ミス、または許可リスト外のアドレスから使われています。キーの一覧で確認するか、新しいキーを作成します。
gateway_key_attempts_exceeded429gatewayRetry-After のあとあなたのアドレスから、受け付けられないキーが多数送られました。ツールが送るキーを修正してから待ちます。
gateway_key_model_not_allowed403gateway不可キーの許可するモデルにこのモデルが含まれていません。一覧のモデルか auto を使うか、キーの許可リストを変更します。
server_application_required403gateway不可リクエストがブラウザから送られた(Origin ヘッダー)か、想定外のクエリ文字列がありました。Gateway はサーバー、CLI、スクリプトから呼び出します。
inference_not_admitted403gateway不可このワークスペースは現在 Gateway を使えないか、選ばれたモデルを使えません。AI Gateway のページから利用を申請してください。
model_not_enabled403gateway不可ワークスペースのモデル設定でこのモデルが除外されています。他のモデルか auto を使うか、オーナーまたは管理者に許可を依頼します。
model_not_found404, 400gateway不可モデルが不明か、このエンドポイントで許可されたモデルのどれもリクエストを処理できません。GET /v1/models の名前か auto を使います。
video_not_found404gateway不可この API キーではこの id の動画は作成されていません。動画は作成したキーでのみ読み取れます。
invalid_model400gateway不可agentlab/… という名前はモデルではなく、auto: の後には cost、balanced、quality だけを指定できます。auto か GET /v1/models の名前を使います。
invalid_provider400gateway不可provider.only にプロバイダーではない名前がある、指定したモデルを除外している、または一覧のプロバイダーにリクエストを処理できるモデルがありません(error.param は provider.only)。一覧を直します。メッセージに有効なプロバイダーが示されます。
unsupported_parameter400gateway不可Gateway が受け付けない OpenAI のフィールドが含まれています(error.param がそのフィールド)。そのフィールドを外します。
prompt_reference_invalid400gateway不可/v1/prompts/{prompt}/completions ではプロンプトを id または slug で指定します。末尾に @<バージョン> を付けられます。
prompt_not_found404gateway不可キーのワークスペースにその名前のプロンプトまたはバージョンがありません。そのワークスペースの「プロンプト」タブを確認してください。
prompt_variables_mismatch400gateway不可variables はプロンプトの変数とちょうど一致する必要があります。メッセージに不足している変数と使われない変数が示されます。
prompt_variables_invalid400gateway不可variables は値がすべて文字列のオブジェクトにしてください。
prompt_messages_not_accepted400gateway不可プロンプトの呼び出しでは messages ではなく variables を送ります。メッセージはプロンプトが持っています。
prompt_too_large400gateway不可変数を埋めたプロンプトがリクエストの上限を超えています。値を短くしてください。
invalid_inference_request400gateway不可Chat Completions の本文に、Gateway が受け付けないフィールドまたは値があります。API リファレンスを参照してください。
invalid_request400gateway不可Responses の本文が保存済みの状態(previous_response_id、conversation、prompt)または拒否されるツールを求めています。param にフィールド名が入ります。
request_key_invalid400gateway不可Idempotency-Key は 1 回まで、8~128 文字で送る必要があります。
request_key_already_used409gateway不可この Idempotency-Key はすでに使われています。新しいリクエストには新しいキーを送ります。
routing_header_invalid400gateway不可X-AgentLab-Routing は auto、auto:cost、auto:balanced、auto:quality のいずれかとし、1 回だけ送ります。
invalid_metadata400gateway不可X-AgentLab-Metadata または本文の metadata のタグを記録できません。メッセージがどの規則に反したかを示します。文字列値が最大 16 個の JSON オブジェクトを 1 つ送ります。キーは英数字・_・.・- の 1〜64 文字、値は 1〜512 文字です。タグを参照。
outcome_subject_not_found404gateway不可このキーのワークスペースに、この id のリクエストやこのトレース id の実行がありません。Gateway が返した X-Request-Id、chatcmpl_… の id、またはトレース id をそのまま送ります。結果の報告を参照。
outcome_window_closed409gateway不可リクエストの送信から 31 日を過ぎたため、結果はもう報告できません。
invalid_outcome400gateway不可outcome は success か failure にし、request_id と trace_id のどちらか一方だけを送ります。
json_required415gateway不可Content-Type: application/json を送ります。
request_too_large413gateway不可本文がエンドポイントの受け付けるサイズを超えています。Chat Completions、音声生成、画像生成は 1 MiB、Messages と Responses は 32 MiB、文字起こしは 26 MiB(音声ファイルは 25 MiB まで)、画像編集と動画は 64 MiB です。
request_body_unreadable400gateway可リクエスト本文が宣言した長さに達する前に途切れたか、時間内に届きませんでした。リクエストを送り直します。
gateway_guardrail_blocked400guardrail不可ワークスペースのガードレールがブロック対象(カード番号、API キー、登録済みの語句など)を見つけました。メッセージにチェック名が含まれます。その内容を削除するか、ワークスペース管理者に AI Gateway › はじめに でガードレールを変更してもらいます。
gateway_routing_rule_rejected403routing_rule不可(1 分間のリクエスト数のルールは Retry-After のあと)ワークスペースのルーティングルールがこのリクエストを拒否しました(例:エンドユーザーの今月の利用額が一定額に達した、キーの送信が速すぎる)。メッセージはワークスペースが書いた文で、ルール名も含まれます。ワークスペース管理者に相談するか、AI Gateway › Gateway 設定 › ルーティングルール でルールを変更します。
inference_allowance_exceeded429gateway不可月間上限、部門の上限、またはローリングウィンドウに余裕がありません。メッセージにどの上限かが書かれます。引き上げるか、リセットを待ちます。 Free プランではプランに含まれるリクエスト数やモデル使用料(gateway_plan_requests、gateway_plan_spend)、従量課金(前払い)ではクレジット残高(gateway_balance)の場合もあります。AI Gateway › プラン でクレジットを追加すると、同じキーですぐに使えます。
gateway_rate_limited429gatewayRetry-After のあとこのキーまたはワークスペースが、レート制限を超える 1 分あたりのリクエスト数またはトークン数を送りました。または、Gateway が同時に処理できる音声・画像・動画のリクエスト数に達しています。待つか、制限を引き上げます。
provider_rate_limited429providerRetry-After のあとモデルプロバイダーが混み合っています。SDK が自動で待ってから再試行します。
count_tokens_concurrency_exceeded429gatewayRetry-After のあとトークン数を数えるリクエストが同時に多すぎます。1 秒ほどしてから再試行します。
provider_overloaded529provider可モデルプロバイダーが過負荷です。少し待って再試行するか、auto または他のモデルを使います。
inference_failed502gateway, provider, model可(1 回)プロバイダーが応答できませんでした。失敗が続く場合は、AI Gateway › 使用量 でそのリクエストを開きます。
settlement_pending503gateway不可モデルは応答しましたが、使用量をまだ記録できなかったため、応答を保留しました。再送しないでください。自動的に確定します。
inference_unavailable503gateway可Gateway が判断に必要なものに接続できませんでした。少し待って再試行します。
gateway_unavailable503gateway可Gateway サーバーが起動中か、設定を再読み込みしています。少し待って再試行します。
gateway_not_configured503gateway不可このサーバーには Gateway が設定されていません。セルフホストの Gateway なら、デプロイの設定を確認します。
transport_deadline_unavailable503gateway可サーバーが接続の制限時間を設定できませんでした。再試行します。

この表はビルドのたびに Gateway のコードと照合されます。Gateway が返しうるコードがこの表にないと、ビルドは失敗します。