Claude API 401 authentication_error / invalid x-api-key

Um 401 do Claude sempre é uma destas cinco coisas: cabeçalho incorreto, tipo de chave incompatível com o endpoint, variável de ambiente malformada, chave revogada ou base URL incorreto para a chave. Execute o diagnóstico abaixo e descubra o seu em menos de um minuto.

O erro

response (HTTP 401)

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

Causas e soluções em resumo

Causa	Solução
Cabeçalho incorreto para o endpoint	A API nativa da Anthropic exige x-api-key + anthropic-version; endpoints compatíveis com OpenAI exigem Authorization: Bearer.
Incompatibilidade entre chave e endpoint	Chaves sk-ant-… funcionam somente com api.anthropic.com; chaves de gateway (por exemplo, sk-kn-…) funcionam somente com a própria URL do gateway.
Espaços em branco ou aspas inseridos na variável de ambiente	Exporte novamente sem aspas ou quebras de linha; imprima len(key) para detectar um \n final vindo de copiar e colar.
Chave revogada ou workspace desativado	Gere uma chave nova no console e faça a rotação no seu gerenciador de segredos.

Reproduza com curl puro (remove seu SDK da equação)

Se o curl funcionar, mas seu aplicativo não, o problema está na configuração do ambiente, não na chave:

diagnose.sh

# Native Anthropic wire (works on api.anthropic.com and Kunavo /v1/messages)
curl -s https://api.kunavo.com/v1/messages \
  -H "x-api-key: $KUNAVO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# OpenAI-compatible wire (Bearer header instead)
curl -s https://api.kunavo.com/v1/chat/completions \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# Check the key isn't carrying whitespace
python3 -c "import os; k=os.environ['KUNAVO_API_KEY']; print(repr(k[:12]), len(k))"

Associe o prefixo da chave à URL base

sk-ant-… → api.anthropic.com. sk-kn-… → api.kunavo.com/v1. Enviar uma chave de gateway para a Anthropic (ou vice-versa) sempre retorna 401 — a mensagem de erro nunca diz "host incorreto", então esse problema fica oculto.

Faça a rotação se a chave já tiver passado por um repositório ou log

Se a chave estiver correta e ainda assim for rejeitada, presuma que foi revogada (scanners automatizados revogam rapidamente chaves expostas). Gere uma nova e armazene-a em um gerenciador de segredos, em vez de arquivos .env que acabam versionados.

Se você estiver chamando pela Kunavo

As chaves Kunavo (sk-kn-…) são autenticadas em qualquer um dos dois cabeçalhos em todos os endpoints — Authorization: Bearer, como os SDKs da OpenAI enviam, ou x-api-key, como fazem os SDKs da Anthropic — portanto, independentemente do SDK usado, somente a URL base muda. As chaves são criadas e revogadas instantaneamente no dashboard. Depois que a chave for autenticada, as tarifas cobradas estão em tabela de preços da Claude API da Anthropic.

Perguntas frequentes

Por que minha chave funciona no curl, mas não no meu aplicativo?

Quase sempre é configuração do ambiente: uma quebra de linha final ao copiar e colar, aspas incluídas no valor, a variável não exportada para o processo ou outro ambiente carregado em produção. Imprima a representação e o comprimento da chave dentro do processo que falha.

Posso usar minha chave do Anthropic Console em um gateway compatível com OpenAI?

Não. Cada serviço autentica apenas suas próprias chaves: as chaves sk-ant pertencem a api.anthropic.com, e as chaves de gateway pertencem ao gateway. Obtenha uma chave da URL base que estiver chamando.

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.

Claude API 401 authentication_error / invalid x-api-key — todas as causas