エラー対照表：Claude Code と Codex で中継 API を使うときのよくあるエラー

この表の使い方

エラー原文から答えを探す前に、どの層の問題かを特定してください。AI クライアントのエラーはほぼこの 5 層に由来します：

1. ネットワーク層：リクエストがサーバーに届いていない
2. 認証層：届いたが key が認められない
3. プロトコル層：key は通ったがパス / 形式が違う
4. モデル層：プロトコルは通ったがモデルが存在しない
5. context 層：モデルは動いているが入力が長すぎる

層に分ける価値はここにあります：層ごとに直し方がまったく違い、しかもエラー原文からはどの層か分からないことが多いからです。

HTTP ステータス別の切り分け

以下のコマンドはモデル一覧と 3 つのプロトコルを確認し、各リクエストの HTTP ステータスを表示します：

curl を実行する同じターミナルで、プレースホルダーを自分の KimiSeek API Key に置き換えて設定してください。クライアントに保存した認証情報は、この環境変数に自動設定されません：

# Replace the placeholder with your own key from the dashboard.
export KIMISEEK_API_KEY="ks-your-key"

# Inspect each HTTP status and error body; a model list does not prove sufficient balance.
# 1. Is the key valid at all? (lists models)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/models\n' https://api.kimiseek.app/v1/models \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}"

# 2. OpenAI Chat Completions
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/chat/completions\n' https://api.kimiseek.app/v1/chat/completions \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'

# 3. Anthropic Messages (the protocol Claude Code speaks)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/messages\n' https://api.kimiseek.app/v1/messages \
  -H "x-api-key: ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}'

# 4. OpenAI Responses (the protocol Codex speaks)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/responses\n' https://api.kimiseek.app/v1/responses \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","input":"ping","max_output_tokens":16}'

各応答の末尾にある HTTP ステータスと、本文の error.code、error.type、message を確認してください。失敗した手順だけでプロトコル対応を判断できません。モデル一覧の 200 はキーの有効性を示すだけで、残高は保証しません。残高 0 なら手順 1 は 200、手順 2 は 402 になる場合があります。

Claude Code 側

認証情報がない

Invalid API key · Please run /login

この文言が出たら、Claude Code が認証情報をまったく取得できていません。ANTHROPIC_AUTH_TOKEN が Claude Code を起動したシェルで有効か確認してください。よくある失敗は、ターミナル A で export し、ターミナル B で起動しているケースです。

401 認証失敗

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid api key"}}

原因を確率順に並べると：

1. key をコピーしたときに空白や改行が入った
2. key が失効済み、または残高を使い切った
3. ANTHROPIC_API_KEY を使ったが値が空で、クライアントがログイン状態にフォールバックした

403 forbidden

API Error: 403 {"type":"error","error":{"type":"forbidden","message":"invalid x-api-key"}}

この文言は直結時には通常 key が無効という意味です。中継経由ではむしろ、リクエストヘッダーの書き方が違うことが原因として多いです。あるゲートウェイは Authorization: Bearer しか受け付けず、別のゲートウェイは x-api-key しか受け付けません。KimiSeek はどちらも受け付けますが、途中にもう 1 段プロキシを挟んでいると header が書き換えられる可能性があります。

model not found

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"model: deepseek-v4-flash-0731 not found"}}

可能性は 2 つ：モデル名の typo、または廃止済みモデルの使用です。廃止済みのモデル id は「廃止されました」ではなく、ずっと not found を返します。ここが最も時間を無駄にする落とし穴で、設定を延々見直した挙げ句、実はモデルが世代交代していたという話になります。

モデルページ で実際の id に置き換えてください。

ストリーミング応答が途中で切れる

API Error: stream disconnected before completion: stream closed before completion

ストリーミング接続が途中で切断されています。次の順に確認します：

1. ローカル HTTP プロキシ（HTTPS_PROXY）が遮断していないか
2. 社内ネットワークに応答タイムアウトがないか
3. サーバー側が 1 リクエストの制限時間に達していないか

上流へのリクエストのタイムアウトは、Claude Code が使う /v1/messages では 600 秒、Codex が使う /v1/responses では 175 秒です。クライアントや途中のプロキシが先に切断する場合もあるため、実際のエンドポイントとエラー内容を確認してください。

context 超過

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 210000 tokens > 200000 maximum"}}

ここでの 200000 はクライアントまたはモデルの上限であり、あなたが想定している数字ではありません。DeepSeek V4 Pro に接続する場合の実際の上限は 1M です。200000 と表示されたなら、リクエストが目的のモデルに届いていないか、クライアントが Claude の仕様に従って打ち切っています。

Codex 側

401 Missing bearer

■ unexpected status 401 Unauthorized: Missing bearer

config.toml の env_key は変数名にすぎず、実際の値は環境に必要です。このエラーは「変数名は書いたが、環境変数が空」という意味です。

404 Not Found

■ unexpected status 404 Not Found

8 割は base_url の /v1 の書き忘れです。Codex は base_url + "/responses" を連結するので、/v1 がないとサイトのパスに飛びます。

base_url を確認した後、応答本文でモデルが見つからないエラーかどうかも確認してください。/v1/responses が本当にない場合は対応ゲートウェイか変換層を使います。現在の Codex は wire_api = "chat" を受け付けません。Codex ガイドも参照してください。

ストリームの中断

■ stream disconnected before completion

Claude Code のストリーミング問題と同じですが、Codex は中断に敏感です。実行ループが完全なイベントストリームに依存しているためです。ネットワークが不安定なときは再試行に頼らず、まずネットワークを変えてください。

ネットワーク層の 2 つの典型

fetch failed
ECONNREFUSED 127.0.0.1:7890

fetch failed は Node の汎用的なネットワークエラーで、字面だけでは情報量がありません。具体的な原因を見るには ECONNREFUSED の行を見ます。127.0.0.1:7890 のようなローカルポートを指しているなら、リクエストがローカルプロキシに引き取られており、そのプロキシが動いていないか設定が誤っています。

この種の問題は「ゲートウェイが落ちた」と誤判定されやすい。判断方法は、curl は通るのにクライアントが通らないなら、ほぼ確実にクライアントが動いているシェルの環境変数が curl を実行したシェルと違う、ということです。

同じ文言でも直結と中継で原因が違う

中継を使うときに最も身につけるべきメンタルモデルです：

質問するときに添えるもの

人に聞く（あるいはチケットを切る）なら、次の 4 点は必須です。ないと誰も原因を特定できません：

1. エラー原文（完全な 1 行。途中で切ったスクリーンショットは不可）
2. curl の層別検証の結果 — 4 ステップのどこで失敗したか
3. クライアントのバージョン（claude --version / codex --version）
4. 使用しているモデル id と Base URL（key はマスクする）

検証日

• 検証日：2026-10-26
• エラー例は原因の切り分け用です。文言はクライアントのバージョンで変わるため、問い合わせ時には実際のバージョン番号も添えてください。Codex の設定は 0.154.0 で確認しています。