401 authentication_error / invalid x-api-keyエラー――確認すべきことを順番に説明

ほぼすべての401は、4つの原因のいずれかによって発生し、「キーが間違っている」のはそのうち1つだけです。他の3つでもキー自体は完全に有効なため、キーを再作成するのは無駄な作業になりがちです。

エラー

resposta (HTTP 401)

{
  "type": "error",
  "error": { "type": "authentication_error",
             "message": "invalid x-api-key" }
}

原因と対処法の概要

原因	対処法
ホストに対するヘッダーが間違っている	Anthropicはx-api-keyを読み取り、OpenAI互換ゲートウェイの多くはAuthorization: Bearerを読み取ります。同じ値でも間違ったヘッダーに入れると、未指定として扱われます。
古い環境変数が残っている	シェルプロファイルに残ったANTHROPIC_API_KEYが、直前にexportしたキーより優先されることがあります。
認証情報を変更せずにベースURLを変更した	別のホストを指定しても、以前のプロバイダーのキーがそこで有効になるわけではありません。ホストと認証情報は一緒に変更します。
キー内の空白、改行、引用符	PDFやチャットからコピーすると、不可視文字が含まれることがあります。文字列の長さを確認してください。

環境に実際に入っている内容を確認する

何かを変更する前に、アプリケーションを実行するのと同じシェルで環境変数を確認してください。驚くほど多くのケースで、異なるプロバイダーの認証情報が同時に2つ定義されています。

conferir.sh

for v in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL; do
  printf '%-22s [%s] tamanho=%s\n' \
    "$v" "$(printenv "$v" | cut -c1-10)" "$(printenv "$v" | wc -c)"
done

アプリケーションの外で認証情報をテストする

直接リクエストを送れば、「ホストがキーを拒否している」のか「アプリケーションがキーを送っていない」のかを切り分けられます。curlが動いてコードが動かないなら、問題は認証情報ではありません。

testar.sh

curl -s -o /dev/null -w 'status=%{http_code}\n' \
  "$ANTHROPIC_BASE_URL/v1/models" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

# 200 -> credencial boa; investigue a aplicação
# 401 -> credencial ou cabeçalho errados para este host

401と403、402を区別する

401は「あなたが誰か分からない」――認証情報が受け付けられていません。403は「あなたが誰かは分かるが、許可されていない」――認証済みですが権限がありません。402は「あなたが誰かは分かるが、残高が不足している」です。認証情報を変更して解決できるのは401だけです。

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

Kunavo は sk-kn- キーを Authorization: Bearer と x-api-key の両方で受け付け、ベース URL はその後にパスを一切付けないサイトのオリジンです。Claude Code では ANTHROPIC_AUTH_TOKEN と ANTHROPIC_BASE_URL を使用してください。トークンは ANTHROPIC_API_KEY が必要とする一度きりの承認に依存しないためです。また、ANTHROPIC_API_KEY は明示的に削除してください。この変数に古い値が残っていることが、設定済みに見えるのにセッションが拒否される最も一般的な原因です。認証の手順は認証ドキュメント.

よくある質問

キーを再作成すれば解決しますか？

キーが実際に取り消されていた場合に限ります。その他の一般的な3つの原因、つまり誤ったヘッダー、古い変数、変更されたベース URL では、新しいキーでもまったく同じように失敗します。

401 は残高不足の可能性がありますか？

いいえ。残高不足は 402 で、クレジットについて説明するメッセージが表示されます。401 は常に身元に関するエラーです。

curl では動作するのに、自分のコードでは失敗します。なぜですか？

ほとんどの場合、コードが別の環境変数を読み込んでいるか、export が届いていない別のシェルまたはコンテナで実行されています。プロセス内で認証情報をマスクして出力し、確認してください。