ERROR LIBRARY
AI API・Codex・Claude Code エラー対処ガイド
元のステータスやエラー文から始め、リクエスト、認証、モデル、ネットワーク、ゲートウェイ、クライアント設定を順に切り分けます。各ガイドに最小再現、修正確認、ログの秘匿範囲を含めています。
共通の診断手順
- 01
元の証拠を保存
ステータス、エラー本文、request ID、UTC 時刻、クライアント版を記録します。
- 02
最小リクエストに縮小
ホスト、キー、モデルを固定し、一度に一つの変数だけ変更します。
- 03
応答レイヤーを特定
クライアント、ネットワークプロキシ、CodeNodex Gateway、モデル上流を分けます。
- 04
確認して秘匿
復旧範囲を再確認し、共有前に認証情報と業務データを削除します。
API レスポンスエラー
HTTP ステータス別に、リクエスト、認証、モデル、レート制限、上流障害を切り分けます。
OpenAI API 400 Bad Request：パラメータ・JSON・形式の確認方法
OpenAI 互換 API の HTTP 400 を、JSON、モデルパラメータ、エンドポイント、クライアントのシリアライズから最小リクエストで診断します。
診断手順を見るHTTP 401API 401 Invalid API Key：Codex・Claude Code・SDK の認証確認
401 Invalid API Key を、接続先ホスト、認証情報の取得元、認証ヘッダー、プロセス環境、クライアント設定の順に追跡します。
診断手順を見るHTTP 403API 403 Forbidden：権限・アカウント状態・ポリシー拒否の確認
モデルアクセス、project role、アカウント制限、接続元ポリシー、ゲートウェイ認可による API 403 を診断します。
診断手順を見るHTTP 404API 404 Model Not Found：model ID・Base URL・ルーティングの確認
HTTP ルートの 404 と model_not_found を区別し、API root、正確な model ID、provider mapping、アカウントのモデル一覧を確認します。
診断手順を見るHTTP 429API 429 Rate Limit：制限・quota・残高・再試行の診断
HTTP 429 が RPM、TPM、同時実行数、quota、残高、予算のどれかを特定し、上限付き backoff と負荷制御を実装します。
診断手順を見るHTTP 500API 500 Internal Server Error：上限付き再試行と上流切り分け
最小 request、model 比較、request ID、制御された retry で API 500 を診断し、副作用の重複を避けます。
診断手順を見るHTTP 502API 502 Bad Gateway：proxy・upstream・レスポンス転送の診断
HTTP 502 を生成したレイヤーを特定し、upstream DNS、TLS、Host/SNI、connection pool、timeout、SSE proxy を確認します。
診断手順を見るHTTP 503API 503 Service Unavailable：過負荷・保守・復旧の確認
retry storm を止め、復旧情報を読み、影響 model・region を絞り、段階的に traffic を戻して API 503 に対応します。
診断手順を見るネットワークとストリーミング
タイムアウト、接続リセット、TLS 証明書、SSE の切断を診断します。
API リクエストタイムアウト：接続・初回バイト・生成・deadline の診断
timeout 値を変更する前に、DNS、TCP、TLS、初回バイト、生成、proxy、job 全体の deadline に分けて API timeout を診断します。
診断手順を見るECONNRESETAPI ECONNRESET / Connection Reset：予期しない接続終了の診断
write、first-byte 待ち、response 読み取りのどこで reset したかを特定し、keep-alive、proxy idle limit、cancel を確認します。
診断手順を見るTLS / SSLAPI SSL Certificate Error：証明書チェーン・host 名・proxy の診断
system time、要求 host、certificate SAN、中間証明書、runtime trust store、TLS intercept proxy を確認して API TLS failure を診断します。
診断手順を見るSSE STREAMOpenAI API Stream Disconnected：SSE 応答中断の診断
non-stream の挙動、raw event framing、proxy buffering、idle timeout、client consumer を比較して OpenAI 互換 SSE の中断を診断します。
診断手順を見るクライアントと設定
コンテキスト上限、Codex、Claude Code Gateway、MCP の起動問題を解決します。
Context Length Exceeded：context window 使用量の診断と削減
instruction、会話履歴、tool schema、file、output reserve に context budget を分解し、必要情報を保って原因を削減します。
診断手順を見るCODEX TOMLCodex config.toml Parse Error：未知項目・階層・strict 検証
実際の Codex version、解決後の CODEX_HOME、backup、strict doctor、一時設定で config.toml parse error を診断します。
診断手順を見るCLAUDE GATEWAYClaude Code Gateway Connection Error：URL・認証・model routing
Messages の Base URL、認証 mapping、model alias、streaming、tool call を検証して LLM gateway 経由の Claude Code を診断します。
診断手順を見るMCP SERVERMCP Server Failed to Start：process・transport・認証・tool discovery
設定 scope から process・HTTP transport、initialize negotiation、tools/list、read-only tool 実行まで MCP startup を診断します。
診断手順を見る