Chave de API inválida? Por que aparece "API Key Data Are Invalid" e como corrigir

O erro "invalid API key" é um dos avisos mais enganosos no trabalho com APIs, porque a chave normalmente não tem nada de errado. O problema quase sempre está em como a chave é armazenada, carregada ou roteada, e não na própria chave. Este guia percorre todas as causas comuns, ensina como ler o erro real retornado pelo provedor (incluindo o conteúdo exato devolvido pela HiAPI) e oferece uma lista pronta para copiar e colar, que valida a chave de ponta a ponta e evita perder uma tarde inteira depurando a aplicação.

Por que uma chave aparentemente correta ainda falha

A seguir estão as causas da grande maioria dos erros de chave inválida, ordenadas aproximadamente por frequência, com a respectiva correção.

Espaços em branco ou quebras de linha no início ou no fim. É a causa número um e também a mais difícil de detectar, porque a chave, ao ser impressa, parece normal. A armadilha clássica é construir o .env com echo, que acrescenta um \n no final:

# Errado — adiciona uma quebra de linha, que passa a fazer parte do valor da chave
echo "HIAPI_API_KEY=sk-..." >> .env
# Correto — sem quebra de linha no final
printf 'HIAPI_API_KEY=sk-...\n' >> .env

Uma quebra de linha no final ou um espaço extra transforma Bearer sk-abc em Bearer sk-abc\n, e o servidor rejeita. Correção: remova isso. No shell: KEY="$(printf '%s' "$KEY" | tr -d '[:space:]')". No código, use key.strip() (Python) ou key.trim() (JS) antes de montar o cabeçalho da requisição.

A chave está na variável de ambiente errada, ou nem sequer foi carregada. Seu código lê HIAPI_API_KEY, mas o seu shell exporta HIAPI_KEY. Ou a variável está definida no seu shell interativo, mas o processo (tarefa cron, contêiner Docker, runner de CI) nunca a herdou. Correção: antes de chamar, imprima o que o processo realmente vê — echo "${HIAPI_API_KEY:0:6}…" — e confirme que o nome da variável corresponde ao que o código lê.

A chave foi revogada, rotacionada ou expirou. Alguém rotacionou a chave, um colega regerou a chave, ou a chave vazou para um repositório público e foi revogada automaticamente. O valor antigo agora está inválido. Correção: gere uma nova chave no console e substitua todas as cópias da antiga.

A chave está sendo enviada ao serviço errado. Enviar uma chave da OpenAI para a HiAPI, ou uma chave da HiAPI para a OpenAI, será rejeitado, porque o serviço receptor não emitiu essa chave. Confirme que a chave e o endpoint pertencem ao mesmo serviço. A requisição de geração da HiAPI usa https://api.hiapi.ai/v1/tasks e uma chave HiAPI.

Esquema Bearer ausente ou mal formatado. O cabeçalho deve ser Authorization: Bearer sk-... — ou seja, a palavra Bearer, um espaço, e depois a chave. Enviar apenas a chave bruta, ou Authorization: sk-..., ou Bearer: sk-..., tudo falha. Correção: confira a string exata do cabeçalho.

A chave foi truncada na cópia. Copiar uma chave longa a partir de um terminal estreito, de uma mensagem de chat ou de um campo de UI rolável pode truncá-la. Correção: compare o comprimento e os últimos caracteres com o console; use o botão de copiar em vez de arrastar para selecionar.

A chave não tem permissão para aquele modelo ou grupo. A chave é válida e foi carregada corretamente, mas não tem permissão para chamar o modelo específico que você está solicitando. Isso é facilmente confundido com "chave inválida", embora na verdade seja um problema de escopo de permissão. Correção: conceda à chave acesso a esse modelo, ou use uma chave que já tenha a permissão.

O erro real da HiAPI (leia, não adivinhe)

Quando a autenticação falha na HiAPI, você recebe HTTP 401, com o seguinte corpo de resposta (verificado na prática):

{
  "error": {
    "code": "permission_denied",
    "type": "hiapi_error",
    "message": "This API key cannot use the selected model. Please check permissions or use another key. If the issue persists, contact support with request ID: 2026...Y7",
    "request_id": "2026...Y7"
  }
}

Três conclusões se tiram disso:

1. O código de status é 401 e o code é permission_denied. A HiAPI não retorna error_key_does_not_exist nem invalid_api_key — essas strings vêm de outros ecossistemas (a OpenAI usa invalid_api_key; error_key_does_not_exist é a formulação genérica de alguns gateways). Se você for comparar códigos de erro na HiAPI, compare permission_denied.
2. A mensagem indica que é um problema de chave/permissão, correspondendo diretamente às duas causas acima: chave errada/ausente, ou chave válida sem acesso ao modelo. Verifique primeiro a chave e depois as permissões do modelo.
3. request_id é o que você deve fornecer ao suporte. Não envie capturas de tela do terminal — cite o request_id. Ele permite que o suporte localize a requisição exata que falhou nos logs.

Leia sempre o corpo JSON da resposta, e não apenas o código de status. Ambos os provedores podem retornar 401, mas a causa real está no corpo da resposta.

Lista de verificação de configuração da chave de API

Antes de depurar o código da aplicação, execute esta lista de cima para baixo para validar qualquer chave. Ela isola a chave do seu framework, do carregamento de ambiente e do cliente HTTP.

1. Copie a chave novamente, usando o botão de copiar do console — nunca selecione manualmente.
2. Remova espaços em branco. Suponha que há uma quebra de linha no final até provar o contrário.
3. Coloque em uma variável de ambiente, não no código-fonte: export HIAPI_API_KEY='sk-...'.
4. Confirme que o processo a enxerga: echo "${HIAPI_API_KEY:0:6}…" deve imprimir o seu prefixo.
5. Confirme a URL base correspondente ao provedor — para a HiAPI, é https://api.hiapi.ai.
6. Faça uma chamada mínima de autenticação (API de tarefas da HiAPI, abaixo).
7. Leia o corpo da resposta. Retornar taskId significa que a chave é válida. Retornar 401 significa reverificar os passos 1–5; retornar permission_denied sobre o modelo significa que a chave não tem acesso a esse modelo.
8. Só então conecte ao aplicativo. Se o curl funciona e a aplicação não, o bug está no carregamento de ambiente ou na montagem do cabeçalho do código — não na chave.

Chamada mínima da HiAPI do passo 6:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2/text-to-image","input":{"prompt":"a red apple on a white table"}}'

O sucesso retorna um taskId; depois consulte GET https://api.hiapi.ai/v1/tasks/<taskId> até que status seja success, e leia a URL da imagem em data.output[0].url. Os detalhes completos estão na documentação da HiAPI. Depois de validada, você pode usar a chave com qualquer modelo — comece pela página do modelo GPT Image 2 e troque alterando o campo model.

Criar e rotacionar chaves

As chaves ficam no console da HiAPI. Para criar uma chave, faça login e gere uma nova — copie imediatamente, porque o valor completo só aparece uma vez. Para rotacionar sem downtime, crie primeiro a nova chave, implante-a em todos os lugares onde a antiga é usada, valide com a lista acima e depois revogue a antiga. Rotacione sempre que houver risco de vazamento, quando um colega sair da equipe, ou quando a produção seguir uma rotação programada.

"claude code invalid api key" — a resposta honesta

Se o Claude Code relata invalid API key, o problema quase nunca está do lado da HiAPI, porque o Claude Code se autentica com a Anthropic. Causas comuns:

• ANTHROPIC_API_KEY errada, expirada ou rotacionada. A Anthropic retorna 401 com authentication_error / "invalid x-api-key". Correção: defina a chave Anthropic atual.
• Configuração residual de base-URL ou de proxy. Se ANTHROPIC_BASE_URL (ou uma configuração de proxy customizada) aponta para um lugar que não aceita a sua chave, toda chamada é lida como inválida. Correção: remova a substituição ou garanta que a chave corresponda ao endpoint para o qual ele aponta.

A HiAPI não corrige chaves da Anthropic nem da OpenAI; essas credenciais são emitidas e verificadas pelos respectivos serviços. Se a sua aplicação usa a HiAPI, chame a API de tarefas unificada com uma chave HiAPI. Apenas alterar a URL base não preserva a estrutura de requisição e resposta da OpenAI.

Perguntas frequentes

Por que minha chave de API parece correta mas é informada como inválida? Porque a causa raramente é a string visível. Em ordem de probabilidade: quebra de linha ou espaço no final (geralmente por usar echo em vez de printf), chave na variável de ambiente errada ou não carregada pelo processo, chave rotacionada/revogada, ou chave enviada à URL base errada. Execute a lista acima — o curl do passo 6 isola a chave da aplicação e, em uma única chamada, mostra se o problema está na chave ou no código.

Como corrigir invalid API key no Claude Code? Defina a ANTHROPIC_API_KEY atual e remova qualquer ANTHROPIC_BASE_URL ou configuração de proxy expirada. A autenticação do Claude Code não tem relação com a HiAPI. Para geração de mídia via HiAPI, chame POST https://api.hiapi.ai/v1/tasks com uma chave HiAPI.

O que é error_key_does_not_exist? É a mensagem genérica de "esta chave não é reconhecida" usada por alguns gateways e ecossistemas de API — significa que o servidor não tem registro da chave que você enviou. Não é um código de erro da HiAPI; a HiAPI retorna HTTP 401 com permission_denied. Na prática, a correção é a mesma: confirme que a chave é a atual, não tem espaços em branco e foi enviada à URL base do provedor correto.

Qual é a diferença entre 401 e 403 aqui? 401 significa que a requisição não passou na autenticação — chave ausente, mal formatada ou não reconhecida. 403/respostas de permissão significam que a autenticação passou, mas a operação específica não é permitida. A HiAPI enquadra a falta de permissão da chave como 401 com permission_denied, então leia a mensagem: se ela menciona um modelo, é um problema de escopo de permissão, e não de chave inválida.

Há uma forma mais rápida de testar a chave do que a aplicação completa? Sim — o curl único da lista. Se ele retornar taskId, a chave está boa, e qualquer falha restante está no carregamento de ambiente ou na montagem do cabeçalho da aplicação. Para conhecer um caminho de produção com crédito de cadastro gratuito, que permite testar geração real antes de pagar, consulte geração de imagens com IA gratuita sem necessidade de chave.