エラーコードとトラブルシューティング

何が失敗したかを特定する

1. 実際の HTTP ステータス、リクエストメソッド、パスを記録してください。HTTP ステータスとアプリケーションのエラーコードは異なる層を表すため、互いに代用しないでください。
2. 呼び出したプロトコルに応じてエラーフィールドを読み取ってください。ネイティブ、OpenAI、Claude、Gemini のレスポンスは、すべて同じ構造ではありません。
3. ストリーミングリクエストでは、エラーイベントと完了状態も確認してください。非同期ジョブでは、ジョブの status を確認してください。HTTP 200 は生成の成功を保証しません。
4. 次の表を使ってリクエストを修正するか、再試行の可否を判断してください。message は説明文であり、安定した列挙値ではありません。その文言を条件分岐に使わないでください。

プラットフォームのエラーコード一覧

以下は、プラットフォームのアプリケーションエラーコードの完全な一覧です。名前は参照用のラベルであり、レスポンスの code の値は数値です。 「一般的な HTTP」はトラブルシューティングの目安であり、すべてのエンドポイントに対する固定の対応関係ではありません。実際の HTTP ステータスとレスポンスボディを確認してください。 上流からそのまま渡された code は、この一覧に含まれない場合があります。

HTTP 429 だけでは、レート制限と同時実行数の制限を確実に区別できません。明示的な数値エラーコードがある場合にのみ区別してください。 モデル一覧でモデル識別子を確認し、model の値を独自に書き換えないでください。

プロトコル別にエラーを読み取る

次の例は、プラットフォームが生成する一般的な構造を示すもので、すべての失敗で保証される単一の形式ではありません。 認証エラーは異なる処理層から返される場合があり、上流からのパススルーレスポンスでは独自の構造、文字列コード、型が保持される場合があります。 解析する前に実際のレスポンスの形を確認してください。認識できない場合は、無理に変換せず、元のフィールドと HTTP ステータスを保持してください。

ネイティブのプラットフォーム API

通常は error.code と error.message を読み取ります。requestId は存在しない場合があります。

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

エラーによっては、最上位の code と message を使用します。クライアントはこの違いを許容し、error オブジェクトがないことを成功の証拠として扱わないでください。 パラメータ検証のレスポンスにも、数値エラーコードが含まれない場合があります。コードがない場合は、勝手に補わず不明として扱ってください。

OpenAI 互換 API

プラットフォームが生成する一般的なエラーは、最上位の code、message、type を使用します。必ずしも error で囲まれているわけではありません。

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type はプロトコル上のカテゴリで、この構造の code はプラットフォームの数値エラーコードです。api_error だけでは、再試行が適切かどうかは判断できません。 上流からのパススルーエラーやストリーミングエラーには、入れ子の error が含まれる場合があります。実際のプロトコルレスポンスに従って処理してください。 Chat Completions と Responses を参照してください。

Claude 互換 API

一般的な構造では、最上位の type が error となり、具体的なカテゴリは error.type、説明は error.message に格納されます。 この構造にはプラットフォームの数値 code は含まれません。勝手に補わないでください。

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

プラットフォームがローカルで生成する Claude のエラー型は次のとおりです。上流のすべてのエラー型を網羅した一覧ではありません。

Claude Messages を参照してください。

Gemini 形式のエラー

Gemini 形式のレスポンスを受け取った場合は、error.code、error.message、error.status を読み取ってください。 ここでの status は文字列のカテゴリであり、HTTP ステータスや非同期ジョブの状態ではありません。

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

この形式でプラットフォームが生成するエラーには、プラットフォームの数値 code が使用されます。ローカルの文字列 status の対応は次のとおりで、上流のすべてのステータスの一覧ではありません。

503 が優先され、INTERNAL ではなく UNAVAILABLE を使用します。上流のレスポンスでは、code や status の意味が異なる場合があります。すべての Gemini の数値コードにプラットフォームのエラーコード表を適用しないでください。

安全な再試行

有効な Retry-After ヘッダーがある場合は従ってください。すべてのエラーに含まれるとは限りません。 冪等でない生成リクエストを自動的に再試行すると、再実行されて追加の料金が発生する可能性があります。このページは、一般的な冪等性キーへの対応を保証するものではありません。自分で Idempotency-Key を追加しても、重複排除は保証されません。

すでに jobId がある場合は、別のジョブを作成する前にそのジョブを照会してください。jobId がなく結果も不明な場合は、調査のためにリクエスト識別子とタイムスタンプを保持してください。

ストリームと非同期ジョブ

SSE リクエスト

SSE の開始後は、後から発生した失敗がストリーム内のエラーイベントやペイロードで通知されても、HTTP ステータスが 200 のままになることがあります。 選択したプロトコルに従ってイベントとデータを解析し、正常に完了したか確認してください。エラーや予期しない切断が発生した場合、部分的なテキストや画像を、完全に成功した結果として扱わないでください。 イベント名とペイロードはエンドポイントごとに異なります。固定された 1 つの error フィールドだけを確認したり、「何らかのテキストを受信した」ことを成功条件にしたりしないでください。

非同期ジョブ

作成レスポンスに data.jobId が含まれていても、それはリクエストが受け付けられたことを意味するだけで、生成の完了を意味しません。 ジョブの照会で HTTP レスポンスが成功した場合、成功したのは照会です。引き続きジョブの data.status を確認する必要があります。

• PENDING、CONNECT、PROCESSING：Jobs のドキュメントに従ってポーリングを続けてください。
• COMPLETED：outputResult を読み取ってください。
• FAILED、CANCELLED：ポーリングを停止し、調査のためにジョブ ID と機密情報を除去したレスポンス情報を保持してください。

失敗の詳細が data.outputResult.error に含まれる場合があります。このフィールドは任意で、すべての失敗したジョブに存在するとは限りません。 Jobs は、作成レスポンスが jobId を明示的に返す場合にのみ使用してください。JSON または SSE で結果を直接返すエンドポイントには、ジョブのポーリングを適用しないでください。

ユーザーと AI アシスタント向けの診断情報

次の情報から機密情報を除去したうえで、サポートまたは AI アシスタントに提供してください。存在しないフィールドには unknown を使用し、HTTP レスポンスを受信していない場合は HTTP ステータスにも unknown を使用してください。 フィールドのパスと元の値の型を保持してください。たとえば error.code: 10000 (number) や error.code: "invalid_api_key" (string) のように記録します。 文字列の code をプラットフォームの数値コードに自動変換したり、message、HTTP ステータス、モデル名から欠けているフィールドを推測して補ったりしないでください。

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

利用できる場合は、レスポンスボディの requestId またはレスポンスヘッダーの X-Request-ID を読み取ってください。長い数値の精度が失われないよう、jobId は文字列として保持してください。 必要最小限の、機密情報を除去したリクエストパラメータだけを提供してください。API キー、トークン、Cookie、認証ヘッダーの全文、個人情報、非公開のプロンプト、入力ファイルの内容を削除してください。 URL のクエリパラメータと、署名やアクセス認証情報を含む入力・出力 URL を削除してください。内容を確認せずにリクエストログ全体を貼り付けないでください。

AI アシスタントは、観測されたフィールドと考えられる原因を区別し、不足する情報を明示する必要があります。証拠が不十分な状態を、リクエストの成功、未実行、または課金がなかったことの証明として扱ってはいけません。