カスタムベースURLでClaude Codeに「API Error: 401 authentication_error」が出る場合

ここでの401は認証情報またはベースURLの問題で、モデルの問題ではありません。モデルの問題なら、モデル名を示すメッセージとともに404が返ります。この1つの違いを押さえるだけで、こうした問題のほとんどは1回のcurlコマンドで解決できます。

エラー

terminal

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

原因と対処法の概要

原因	対処法
ANTHROPIC_AUTH_TOKENを設定すべき場所にANTHROPIC_API_KEYを設定している	サードパーティのベースURLにはAUTH_TOKENを使用します。API_KEYでは初回承認プロンプトが表示されます。
/v1パスを含むベースURL	オリジンだけを設定してください。Claude Code自身が/v1/messagesを追加します。
キーが取り消されている、またはアカウントが停止されている	どちらも403ではなく401を返します。新しいキーを発行し、アカウントを確認してください。
Messagesエンドポイントが提供していないモデル	この場合はモデル名を示す404が返り、401ではありません。したがって別の修正が必要です。

3つの変数を表示し、ベースURLにパスがないことを確認する

最も一般的な原因はここで確認できます。クライアント自身がエンドポイントを追加するため、ベースURLはオリジンでなければなりません。/v1も末尾のパスも付けないでください。/v1で終わるベースURLを設定すると、/v1/v1/messagesへリクエストが送られます。

check-env.sh

env | grep -E '^ANTHROPIC_(BASE_URL|AUTH_TOKEN|API_KEY|MODEL)='

# Right: https://api.kunavo.com
# Wrong: https://api.kunavo.com/v1

エンドポイントを2通りで直接呼び出す

Kunavoの/v1/messagesは、x-api-keyまたはAuthorization: Bearerのどちらでも認証情報を受け付けます。そのためClaude Codeの前にプラグインやプロキシは必要ありません。curlが成功してCLIが失敗するなら、問題はサーバーではなくシェル環境にあります。

probe.sh

curl -s https://api.kunavo.com/v1/messages   -H "x-api-key: $ANTHROPIC_AUTH_TOKEN"   -H "anthropic-version: 2023-06-01"   -H "content-type: application/json"   -d '{"model":"claude-sonnet-5","max_tokens":8,
       "messages":[{"role":"user","content":"hi"}]}'

# Same call, other header style — both are accepted:
#   -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

使用していない変数の設定を解除する

ANTHROPIC_API_KEYとANTHROPIC_AUTH_TOKENの両方が設定されていると、誤ったほうが優先される可能性があります。ANTHROPIC_API_KEYの設定を解除し、新しいシェルを起動して再試行してください。シェルのプロファイルに残った古いexportは、他のどの修正よりも長く影響します。

ステータスが404なら、キーのデバッグをやめる

モデル名を示す404は、認証情報は受け付けられたものの、モデル文字列は受け付けられなかったことを意味します。修正すべきなのはANTHROPIC_MODELであり、キーに問題はありません。新規セットアップでよくある原因は、モデルが何も固定されていないことです。その場合Claude Codeは組み込みのデフォルトである最新のOpusを送信しますが、Kunavoではまだ提供されていない可能性があります。また、/model sonnetはKunavoが提供していないSonnet 5.5を要求します。ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODELを、GET /v1/modelsで取得したIDに設定してください。

Kunavo経由で呼び出している場合

Kunavoからの401は5つの原因に絞れます。Authorization: Bearerまたはx-api-keyのどちらにもキーが届いていない、キーにsk-kn-プレフィックスが付いていない、Kunavoが発行していないsk-kn-キーである（タイプミスまたは貼り付けの途中で切れている）、キーが取り消されている、またはアカウントが停止されている、のいずれかです。これらはいずれも403にはなりません。そのためステータスコードだけで原因の系統が分かります。また、Messagesエンドポイントが提供していないモデルに有効なキーを向けた場合は、401ではなく、メッセージ内でモデル名を示す404が返ります。これが診断ツリーの全体です。

よくある質問

curlではキーが使えるのに、Claude Codeでは使えないのはなぜですか？

ほとんどの場合、シェルプロファイルに設定された2つ目の変数か、パス付きのベースURLが原因です。エンドポイントは両方のヘッダー形式に対応しているため、違いはヘッダーではありません。

ANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEYのどちらを使うべきですか？

サードパーティのベースURLにはAUTH_TOKENを使用します。すぐに使われます。API_KEYでは先に初回承認プロンプトが表示されるため、失敗と誤解されることがあります。

ClaudeのサブスクリプションでカスタムベースURLを利用できますか？

いいえ。サブスクリプションはベンダー独自のエンドポイントへの認証に使われます。CLIの接続先を別の場所に変更すると、そのエンドポイントの認証情報が必要になり、そのエンドポイントの料金体系で課金されます。

カスタムベースURLでClaude Codeに「API Error: 401 authentication_error」が出る場合 — すべての原因

エラー