Dados da chave de API inválidos: causas deste erro e como corrigi-lo

Ao chamar a hiapi, ver uma mensagem como "the api keys data are invalid" (ou uma variante semelhante exibida pela sua aplicação) significa que a requisição não passou pela autenticação. Nos bastidores, a própria API da hiapi retorna um erro específico para isso: HTTP 401, error.code: "permission_denied", com a mensagem "This API key is invalid. Check that it is correct or use another API key and try again." (Esta chave de API é inválida. Verifique se está correta ou use outra chave de API e tente novamente.) Qualquer aplicação que encapsule a hiapi — proxies de backend, clientes compatíveis com OpenAI, SDKs internos — irá relabelar o mesmo 401 com suas próprias palavras, e é por isso que o texto exato que você vê raramente coincide com o original da hiapi. Este guia explica passo a passo por que isso acontece e como confirmar e corrigir o problema em poucos minutos.

Como o erro realmente se parece

Uma requisição com falha a POST https://api.hiapi.ai/v1/tasks (ou a qualquer outro endpoint da hiapi) retorna:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again. If the issue persists, contact support with request ID: <id>",
    "request_id": "<id>",
    "type": "hiapi_error"
  }
}

O código de status HTTP é 401. Se o seu framework ou SDK não expõe a resposta bruta, ele pode reempacotar isso numa mensagem genérica de "API key(s) data are invalid", "unauthorized" ou "invalid credentials" — mas a causa raiz no lado da hiapi é sempre o mesmo 401.

Causas comuns (da mais provável para a menos provável)

1. O valor da chave está errado. Copiar e colar truncado, um espaço a mais, ou copiado de uma anotação antiga em vez da chave ativa em Dashboard → API Keys — qualquer um desses casos dispara exatamente este erro: seja a chave ilegível, vazia ou inexistente, a mensagem retornada pela hiapi é idêntica.
2. A chave de placeholder nunca foi substituída. Códigos copiados de tutoriais ou templates costumam trazer uma string literal como sk-your-api-key — ela produz exatamente o mesmo 401 que uma string aleatória.
3. A chave foi rotacionada ou revogada. Criar uma nova chave no painel não invalida automaticamente a antiga, mas revogar ou regenerar manualmente sim — se alguma implantação ainda referencia o valor antigo (variável de ambiente não reimplantada, .env não recarregado), toda requisição dará 401.
4. A chave está sendo enviada no cabeçalho errado. A hiapi só lê a chave do cabeçalho Authorization. Enviá-la como x-api-key, api-key ou como parâmetro de query produz a mesma resposta permission_denied, porque nesse caso a hiapi nem vê a chave mal formatada — ela simplesmente não vê chave alguma.
5. A variável de ambiente em runtime está vazia. Se o seu processo lê a variável da chave antes de carregar o arquivo .env, ele envia uma string vazia como chave — novamente 401.
6. Espaços em branco ou quebras de linha ocultos se misturam à chave. Isso é sutil: passar um segredo por pipe com echo num script de shell acrescenta uma quebra de linha ao final do valor. Se ela entrar no cabeçalho Authorization, corrompe a requisição de outra forma — não um 401 limpo, mas um 400 com uma mensagem confusa de invalid json body, porque o cabeçalho corrompido vaza para o corpo da requisição. Se o seu erro parecer uma requisição mal formatada em vez de um "invalid key" limpo, verifique primeiro se há espaços em branco ou quebras de linha perdidos na chave.

Corrija na ordem

1. Abra Dashboard → API Keys e copie a chave novamente. Não reutilize valores do histórico antigo do terminal ou de mensagens — copie diretamente da página.
2. Confirme que o formato do cabeçalho corresponde exatamente: Authorization: Bearer YOUR_API_KEY. Se você monta esse valor em um script de shell, use printf em vez de echo — echo acrescenta uma quebra de linha final que printf não acrescenta.
3. Imprima o valor antes de enviar a requisição (console.log, print ou log de depuração) para confirmar que não está vazio e não tem aspas, espaços ou quebras de linha perdidos.
4. Teste a chave isoladamente com uma chamada simples de curl (veja abaixo). Se o curl funcionar e a sua aplicação continuar falhando, o bug está em como a sua aplicação monta a requisição, não na chave em si.
5. Verifique o código de status HTTP exato que você recebeu. 401 é este erro. 402 significa saldo vazio na conta, não chave errada. 403 significa que a chave é válida mas falta permissão para aquele modelo específico. 429 significa que você está sendo limitado por taxa. Nenhum desses três deve ser tratado como problema de chave inválida.

Exemplo mínimo de verificação

Execute o comando abaixo diretamente (substituindo pela sua chave real) para confirmar se a chave em si tem problema:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2", "input": {"prompt": "uma pequena maçã vermelha sobre um fundo branco"}}'

Uma chave válida retorna imediatamente um ID de tarefa:

{"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

Uma chave errada retorna o 401 mostrado acima. Se o curl retornou uma resposta com taskId mas a sua aplicação ainda lança o erro "invalid key", o problema está no código de montagem da requisição da sua aplicação, não na chave.

Conteúdo relacionado

• Documentação de autenticação —— formato completo do cabeçalho, guia de rotação de chaves e referência de códigos de status.
• Dashboard → API Keys —— local para criar, copiar e revogar chaves.
• Limites de taxa —— diferença entre 429 e 401 e condições de disparo.
• Quickstart —— se você está configurando a hiapi pela primeira vez, aqui está um passo a passo completo da primeira requisição.

Perguntas frequentes

"invalid API key" e limite de taxa são a mesma coisa? Não. O 401 permission_denied significa que a chave em si não foi aceita. Um 429 com error_code: "RATE_LIMITED" significa que a chave está boa, mas a requisição chegou rápido demais — consulte os limites na documentação de limites de taxa.

Acabei de criar uma nova chave, mas ela ainda é inválida — por quê? Confirme que a nova chave foi realmente copiada para o local que faz a requisição. Uma nova chave no painel não corrige automaticamente um valor antigo gravado no código, uma variável de ambiente não definida ou um arquivo de configuração não reimplantado.

A hiapi exige a palavra literal "Bearer" no cabeçalho? O formato documentado e suportado é Authorization: Bearer YOUR_API_KEY — sempre use esse. Não dependa de qualquer comportamento tolerante que você possa ter observado em testes; comportamentos não documentados podem mudar sem aviso.

Por que o curl funciona e a minha aplicação não? Se o curl com a mesma chave funciona, a chave é válida e o problema está em como a sua aplicação monta a requisição — geralmente falta o prefixo Bearer no código, a variável de ambiente é lida antes do carregamento do .env, ou a chave é passada para o parâmetro errado na biblioteca de wrapper.

O que significa error.type: "hiapi_error"? É o envelope genérico de erro da hiapi, usado tanto para esta falha de autenticação quanto para outros erros de requisição. Verifique error.code (aqui, permission_denied) para entender o erro real, e não apenas o tipo do envelope.