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

エラーの発生元とHTTPステータスから呼び出し問題を特定し、安全な復旧方法を選択します。

APIリクエストが失敗した場合は、まずHTTPステータスコードと機密情報を除いたエラーメッセージを保存し、問題がリクエスト、認証、モデル、サーバーのいずれにあるかを判断します。原因を確認しないまま同じリクエストを繰り返し送信しないでください。

認証情報と顧客データを最初に保護してください

トラブルシューティング記録には、完全なAPI Key、Authorizationまたはx-api-key Header、Cookie、パスワード、完全なPrompt、顧客ファイル、その他の機密情報を含めないでください。

エラーの発生元を最初に判断する

発生元	よくある症状	推奨対応
リクエスト内容	JSONが無効、フィールド不足、パラメータ型の誤り、ファイル形式が要件外	エラー情報に従って修正し、同じ内容のまま再試行しない
認証と権限	API Keyがない、無効、または現在のKeyで対象モデルを利用できない	Base URL、プロトコルの認証Header、Keyの状態、モデル権限を確認する
モデルとリソース	モデルID、タスクID、リクエストパスが存在しない	モデルマーケットプレイスからIDを再取得し、リソースが属するアカウントを確認する
プラットフォームまたは上流	サービスが一時的に利用できない、処理がタイムアウトした、上流がエラーを返した	診断情報を保存して限定的に再試行し、失敗が続く場合はリクエストを停止する
非同期タスク	送信後に失敗した、長時間処理中のまま、または結果を利用できない	元のタスク状態を先に照会し、すぐに重複タスクを作成しない

同じ失敗に複数の手掛かりが含まれることがあります。たとえば404はエンドポイントの誤りだけでなく、モデルやタスクが存在しない場合にも返されるため、最終的なリクエストURLとエラー本文を併せて判断してください。

HTTPステータス	一般的な意味	推奨する復旧方法
`400`	リクエスト形式、パラメータ、入力内容に誤りがある	リクエストを修正してから再送信する
`401`	API Keyがない、無効、または認証Headerがインターフェース要件と一致しない	プロトコルの認証方式を確認し、必要に応じて新しいKeyを作成して置き換える
`403`	現在のアカウント、Key、モデルの利用範囲がリクエストを満たさない	アカウント状態、トークン制限、モデル権限を確認する
`404`	Base URL、エンドポイント、モデル、タスクが存在しない	最終URL、モデルID、タスクID、所属アカウントを確認する
`429`	リクエスト頻度、同時実行数、クォータ、サービス容量の制限を受けている	高頻度のリクエストを停止し、実際のエラーに従って負荷を下げて後で再試行する
`500`–`599`	プラットフォーム、ゲートウェイ、上流サービスが一時的に処理を完了できない	診断情報を保存し、回数を限定したバックオフ再試行を行う

これらのステータスは調査方向をすばやく判断するためのものです。プロトコルや上流によってプログラムエラーコードが異なるため、HTTPステータス、実際のエラー本文、対応するAPI Referenceを併せて確認してください。

情報	例または説明
発生時刻	日付、時刻、タイムゾーンを含める
リクエスト位置	MethodとPath。完全なAPI Keyは含めない
呼び出し対象	モデルID。非同期タスクではタスクIDも指定できる
レスポンス結果	HTTPステータスと機密情報を除いたエラーメッセージ
リクエスト特性	ストリーミング、ツールの有無、非同期タスクかどうか
クライアント環境	SDK名とバージョン、ランタイムのバージョン、最小再現手順
追跡情報	レスポンスに存在する場合はRequest IDを保存

プログラムエラーコードと対処方法を確認する場合は、エラーコードリファレンスを参照してください。解決しない場合は、Request IDとFAQも確認してください。初回接続の問題については、クイックスタートとAPI Keyと認証を再確認してください。