Claude Media
Claude Code「Invalid API key」エラーの原因と対処法
Claude Codeチュートリアル

Claude Code「Invalid API key」エラーの原因と対処法

「Invalid API key」はキーの失効・誤入力だけでなく、貼り付け時の改行混入や環境変数の優先順位でも起きます。メッセージの続き方と設定元で原因を切り分けます。

読了目安 約13分

Invalid API keyは「キーは送られたが拒否された」状態

Invalid API key · Fix external API key は、ANTHROPIC_API_KEY 環境変数か apiKeyHelper スクリプトが返したキーをAPIが拒否したとき、あるいはClaude Codeがキーを送信前に自ら止めたときに出ます。「資格情報が見つからない」Not logged in とは違い、キーは存在するのに使えない状態です。

Invalid API key · Fix external API key

似たメッセージが3つあり、どれが出ているかで探す場所が変わります。

見分け方

似ている3つのエラーと、疑う場所

  • Invalid API key

    ANTHROPIC_API_KEY の値、または apiKeyHelper が返したキーが拒否された。失効・取り消し・タイプミスに加え、改行などの混入もここに出ます。

  • Invalid auth token

    ANTHROPIC_AUTH_TOKEN か CLAUDE_CODE_OAUTH_TOKEN の値に、HTTPヘッダーで運べない文字が入っている。

  • Your apiKeyHelper script is failing

    apiKeyHelper の実行が失敗した、何も出力しなかった、キー以外のものを出力した。キーの中身ではなくスクリプトが原因です。

メッセージが Fix external API key で終わるかどうかも手がかりです。続きに説明が付く場合の読み方は、「貼り付け由来の不可視文字」の節にあります。

キーの取り消しとタイプミスを先に確認する

Console(platform.claude.com)でキーが取り消されていないか、タイプミスがないかを確認します。次に、同じシェルで実際に渡っている環境変数を見ます。

env | grep ANTHROPIC

Windows PowerShellでは次のコマンドを使います。

Get-ChildItem Env:ANTHROPIC*

direnvやdotenv系のシェルプラグイン、IDEのターミナルは、プロジェクト内の .env ファイルから古いキーを読み込むことがあります。自分でexportした覚えがなくても、この経路でキーが設定されている場合があります。

サブスクリプション認証に戻したい場合は、環境変数を解除してから /login します。

unset ANTHROPIC_API_KEY

ANTHROPIC_API_KEY や apiKeyHelper が有効なあいだは、/login だけでは切り替わりません。環境変数と apiKeyHelper は保存済みのログインより優先されるためです。優先順位は次のとおりです(上ほど強い)。Bedrock・Vertex・Foundryなどのクラウドプロバイダー設定は、さらに上にあります。

  1. ANTHROPIC_AUTH_TOKEN 環境変数
  2. ANTHROPIC_API_KEY 環境変数
  3. apiKeyHelper スクリプトの出力
  4. CLAUDE_CODE_OAUTH_TOKEN 環境変数
  5. Anthropicプロファイルとフェデレーション認証情報
  6. /login で保存したサブスクリプションのログイン

5番のプロファイルは、ant auth login が書いたものを ANTHROPIC_PROFILE で指名したときだけこの位置に入ります。指名しなければ /login の下です。つまりプロファイルを使う環境では、/login より上に別の認証が入ることがあります。

ANTHROPIC_API_KEY と ANTHROPIC_AUTH_TOKEN が両方ある場合は、ANTHROPIC_AUTH_TOKEN が使われます。Consoleでキーが有効なのに Invalid API key が出るときは、この表のどれが実際に効いているかを疑います。

手元のclaudeが、環境変数をどう見るか

ネットワークに出さずに確かめられる範囲を、v2.1.285で試しました。CLAUDE_CONFIG_DIR を空のディレクトリに向け、未ログインの状態で claude auth status を実行した結果です。

claude auth status --text

未ログインのJSON出力(既定)は "loggedIn": false / "authMethod": "none" でした。ここに環境変数を1つ足すと、表示が変わります。

ANTHROPIC_API_KEY=sk-ant-test claude auth status --text
# => API key: ANTHROPIC_API_KEY
 
ANTHROPIC_AUTH_TOKEN=x claude auth status --text
# => Auth token: ANTHROPIC_AUTH_TOKEN

JSON出力では "loggedIn": true と "apiKeySource": "ANTHROPIC_API_KEY" が加わります。2つを同時に設定すると "authMethod": "oauth_token" と "apiKeySource": "ANTHROPIC_API_KEY" が並び、authMethod の名前だけでは実際にどちらが使われるか読み取れませんでした。

もう1点、値の中身は判定されません。値に改行を含めたキー(sk-ant-x の次の行に abc)を渡しても、出力は上と同じ API key: ANTHROPIC_API_KEY で、問題があるという表示は出ませんでした。claude auth status が確認できるのは「どの設定元がキーを供給しているか」までで、キーが有効か壊れているかは、実際にリクエストを送るまで分かりません。

対話画面の /status も、API key の行で設定元を確認する用途です。

/status

ログインとAPIキーが両方あるときは、使われていない API key 行に「not in use」の印が付くことがあります。

貼り付け由来の不可視文字を疑う

メッセージに Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines). のような説明が続く場合、原因はキーの値そのものです。HTTPヘッダーは改行・NULバイト・U+00FF を超える文字(カーブした引用符やゼロ幅スペースなど)を運べません。Claude Codeはこれを送信前に検知して止めるため、APIまでキーは届いていません。

説明文の仕組みは次のとおりです。

  • 位置は1から数えた文字数で示される
  • 「line break」「zero-width space」「curly quote」のように名前が出るのは、バイトオーダーマーク・ゼロ幅スペース・カーブした引用符など、よく知られた不可視文字・装飾文字のとき。それ以外は a non-ASCII character と表示される
  • 説明は定型句と文字数だけで組まれ、キーの値そのものは含まれない

典型的な原因は、ドキュメントやチャットからコピーしたときに混入した不可視文字か、折り返しで入った改行です。対処は再入力で、同じ場所からもう一度貼り付けず、報告された位置の前後を手で打ち直します。

このチェックが走るのは、Claude APIへ直接、またはLLMゲートウェイ経由で送るときです。Amazon Bedrockのようなサードパーティのクラウドプロバイダーでは、送信前のこの検査は行われません。

環境変数ごとに、出るメッセージが変わる

同じ「不可視文字の混入」でも、どの変数が壊れているかで先頭のメッセージが変わります。

壊れている値先頭に出るメッセージ
ANTHROPIC_API_KEY先頭に出るメッセージInvalid API key
ANTHROPIC_AUTH_TOKEN / CLAUDE_CODE_OAUTH_TOKEN先頭に出るメッセージInvalid auth token
ANTHROPIC_CUSTOM_HEADERS先頭に出るメッセージInvalid ANTHROPIC_CUSTOM_HEADERS
/login で保存した資格情報先頭に出るメッセージNot logged in

ANTHROPIC_AUTH_TOKEN は、LLMゲートウェイがBearerトークンで認証する構成で使う変数です。

Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).

ANTHROPIC_CUSTOM_HEADERS の場合、説明は「3つ中2番目のヘッダー」のように何番目のペアが原因かだけを示し、名前や値は繰り返しません。どの変数を設定しているか分からなくなったら、env | grep ANTHROPIC の結果から確認します。ゲートウェイでは認証ヘッダーも変数で異なり、ANTHROPIC_AUTH_TOKEN は Authorization: Bearer、ANTHROPIC_API_KEY は x-api-key、apiKeyHelper は両方に入ります。キーを入れる変数を取り違えると、ゲートウェイがそのヘッダーを読まず 401 を返します。

apiKeyHelperが原因のときの見え方

apiKeyHelper を使っている場合、Invalid API key と Your apiKeyHelper script is failing の2つを区別します。

  • Invalid API key: スクリプトはキーらしい文字列を返し、APIがそれを拒否した。スクリプトを単体で実行し、返る値がConsoleで有効なキーかを見る
  • Your apiKeyHelper script is failing: 終了コードがエラー、タイムアウト、何も出力しない、キー以外(ログインバナーやログの一行)を出力した、のいずれか

後者では、キーが取れないままプレースホルダーの資格情報で送られたリクエストが 401 で拒否されます。すると、Claude Codeがスクリプトを再実行してリクエストを最大2回やり直し、3回目までに上のメッセージを出します。キー以外のものが混ざったときは、returned output that cannot be used as an API key と理由が Authentication パネルに出ます(出力の内容は繰り返されません)。v2.1.227より前は、前後の空白を除いただけの出力がそのままキーとして送られていました。

apiKeyHelper の出力は、標準出力に印字可能なASCIIの1トークンだけを、16,384文字以内で出力し、終了コード0で終わる形が条件です。また、スクリプトの出力は上の送信前チェックには回らず、スクリプトの実行時に検証されます。ヘッダーで運べない文字を含む出力は Invalid API key ではなく、Your apiKeyHelper script is failing になります。

失敗中は /status の apiKeyHelper 行が Failing になり、終了コードとエラー出力が併記されます(v2.1.274より前は設定元だけの表示)。次の実行に成功すると、この行は消えます。

キャッシュの寿命は既定で5分です。5分が過ぎたとき、またはAPIが 401 か 403 を返したときに再実行されます。キャッシュした出力がJWTで、その期限が切れたときも再実行されます(v2.1.246以降)。

401・403 とJWT期限切れの2条件は、apiKeyHelper の出力がそのまま送る資格情報で、かつ ANTHROPIC_AUTH_TOKEN が未設定のときだけ働きます。ANTHROPIC_AUTH_TOKEN を併用していると、この2条件での再実行は働きません。

CLAUDE_CODE_API_KEY_HELPER_TTL_MS にミリ秒を指定すると寿命を変えられます。900000 なら15分です。

意図しないキーが、サブスクリプションを上書きする

サブスクリプションでログイン済みなのに、シェルに残った ANTHROPIC_API_KEY が使われる場合、出るメッセージは Invalid API key とは限りません。無効化された組織のキーなら Your ANTHROPIC_API_KEY belongs to a disabled organization (This organization has been disabled の項目)、残高切れの組織のキーなら Credit balance is too low が出ます。どちらも /status の API key 行に承認済みのキーが出ていれば、それが上書きの原因です。

対処は同じで、現在のシェルと、シェルの設定ファイルの両方から ANTHROPIC_API_KEY を消してから claude を起動し直します。まだサブスクリプションでログインしていない場合は /login も要ります。

くらべる

対話モードと -p で、キーの扱いが違う

承認を求める

対話モード

初回にキーを承認するか聞かれ、選択は記憶されます。あとから変えるときは /config の「Use custom API key」を切り替えます。この項目は ANTHROPIC_API_KEY が環境にあるあいだだけ表示されます。

常に使う

非対話モード(-p)

ANTHROPIC_API_KEY が設定されていれば、承認を挟まず常にそのキーが使われます。CIで古いキーが使われ続けていたら、パイプラインの環境変数の棚卸しが最初の一手です。apiKeyHelper が失敗したときは、stderrに apiKeyHelper failed: で始まる具体的な理由も出ます。

よくあるつまずき

キーのローテーション後に古い値が残る

Consoleで新しいキーを発行しても、シェルの環境変数や .env ファイル、CIのシークレット設定を更新し忘れていると、取り消し済みの古いキーが使われ続けます。キーを使っている箇所を横断的に洗い出します。

スライドやドキュメントからコピーしたキー

書式付きテキストのコピーは、見た目に分からない改行やスペースを持ち込むことがあります。報告された位置の前後を打ち直す対処は、先の節のとおりです。

CIのシークレットでだけ失敗する

ローカルの同じキーでは通り、CIでだけ Invalid API key が出るなら、シークレットの登録時に混入したものがないかを疑います。エラーの説明文に文字位置が付いていれば、登録した値の該当位置を見ます。

.env を書いたのに反映されない

プロジェクトの .env は、direnvのようなツールを介さない限りシェルには読み込まれません。設定したはずなのに効かないときは、そのファイルが実際に読み込まれる仕組みかを確認します。逆に、消したはずの古いキーが .env 経由で居座っている場合もあります。Claude Codeが参照する環境変数の一覧はClaude Code環境変数リファレンスにあります。

ANTHROPIC_API_KEY の設定元を見つけたあとの、認証方式の使い分けはClaude Codeログイン方法3種の使い分けで扱っています。

まとめ

Invalid API key の後ろに文字位置の説明が付くか、/status の API key 行に何が出るか。この2点で、キーの破損なのか設定元の取り違えなのかが分かれます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →