Erro 401 authentication_error / invalid x-api-key — o que verificar, na ordem

Quase todo 401 tem uma de quatro causas, e só uma delas é "a chave está errada". As outras três deixam a chave perfeitamente válida — por isso recriar a chave costuma ser esforço desperdiçado.

O erro

resposta (HTTP 401)

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

Causas e soluções em resumo

Causa	Solução
Cabeçalho errado para o host	A Anthropic lê x-api-key; a maioria dos gateways compatíveis com OpenAI lê Authorization: Bearer. O mesmo valor no cabeçalho errado chega como ausente.
Variável de ambiente antiga sobrando	Uma ANTHROPIC_API_KEY esquecida no perfil do shell pode vencer a que você acabou de exportar.
Base URL trocada sem trocar a credencial	Apontar para outro host não torna a chave do provedor anterior válida ali. Host e credencial mudam juntos.
Espaço, quebra de linha ou aspas na chave	Copiar de um PDF ou de um chat costuma trazer caracteres invisíveis. Confira o comprimento da string.

Verifique o que o ambiente realmente contém

Antes de mudar qualquer coisa, olhe as variáveis no mesmo shell que executa a aplicação. Uma parte surpreendente dos casos tem duas credenciais definidas ao mesmo tempo, de provedores diferentes.

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

Teste a credencial fora da aplicação

Uma requisição direta separa "o host recusa a chave" de "a aplicação não envia a chave". Se o curl funciona e o código não, o problema não é a credencial.

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

Separe 401 de 403 e de 402

401 é "não sei quem você é": a credencial não foi aceita. 403 é "sei quem você é e não pode": autenticado, sem permissão. 402 é "sei quem você é e falta saldo". Só o 401 se resolve mexendo na credencial.

Se você estiver chamando pela Kunavo

A Kunavo lê a chave sk-kn- tanto em Authorization: Bearer quanto em x-api-key, e a base URL é a origem do site sem nenhum caminho depois. Com o Claude Code, use ANTHROPIC_AUTH_TOKEN mais ANTHROPIC_BASE_URL, porque o token não depende da aprovação única que a ANTHROPIC_API_KEY exige, e remova a ANTHROPIC_API_KEY explicitamente — um valor antigo nessa variável é a causa mais comum de uma sessão que parece configurada e mesmo assim recusa. O passo a passo de autenticação está na documentação de autenticação.

Perguntas frequentes

Recriar a chave resolve?

Só se a chave tiver sido mesmo revogada. Nas outras três causas mais comuns — cabeçalho errado, variável antiga, base URL trocada — a chave nova falha exatamente igual.

401 pode ser falta de saldo?

Não. Saldo insuficiente é 402, com uma mensagem que fala de créditos. O 401 é sempre sobre identidade.

Funciona no curl e falha no meu código. Por quê?

Quase sempre o código lê outra variável de ambiente, ou roda em outro shell/container onde o export não chegou. Imprima a credencial mascarada dentro do processo para confirmar.

Guias relacionados

Mais detalhes sobre o significado dos erros estão em referência de erros; obter uma chave leva um minuto por meio de cadastro e da guia de autenticação.