HiAPI retorna 403 sem permissão de modelo: guia de diagnóstico e correção

Ao chamar a interface /v1/tasks da HiAPI, se você receber um HTTP 403, o corpo da resposta normalmente tem esta estrutura: {"error": {"code": "permission_denied", "message": "...", "request_id": "...", "type": "hiapi_error"}}. Isso indica que sua API Key em si é válida e a autenticação já passou, mas essa Key não está autorizada a chamar o modelo ou a interface que você solicitou — isso é um tipo de problema diferente do 401 de "Key inválida ou ausente": o 401 é quando a identidade nem foi reconhecida, e o 403 é quando ela foi reconhecida, mas essa Key não tem permissão para usar o recurso atual. A correção da maioria dos 403 é direta: verifique a correspondência entre a Key e o modelo e tente novamente com uma Key que tenha permissão.

Causas comuns

1. A API Key não está autorizada a usar o modelo solicitado — a definição de 403 na documentação oficial é exatamente "a chave de API não tem essa permissão"; este é o cenário mais comum, geralmente ocorre quando a mesma Key é usada para chamar um modelo fora do escopo de permissão dela.
2. Key errada — por exemplo, você deveria usar a Key principal, mas usou por engano uma Key de outra conta ou projeto com escopo de permissão menor; ao copiar e colar, também é fácil incluir espaços extras ou truncar o valor.
3. Confundir "chave inválida" (401) com "chave sem permissão" (403) — ambas podem conter palavras relacionadas a "permissão" na mensagem de erro, e investigar com a mesma abordagem leva à direção errada; veja abaixo como diferenciá-las.

Passos de correção

1. Primeiro confirme que o retorno é realmente 403 e não 401 — observe o próprio código de status HTTP, não apenas o texto da mensagem de erro, porque o código de erro permission_denied pode aparecer tanto em 401 quanto em 403; o critério de distinção é o código de status, não o texto.
2. Vá até Gerenciamento de chaves de API e confira a qual conta pertence esta Key — confirme que a Key realmente usada na requisição é a esperada, e não uma Key de conta de teste, projeto antigo ou de outra pessoa.
3. Verifique se o modelo atual está dentro do escopo disponível para esta Key — consulte a documentação de autenticação e a precificação da HiAPI para confirmar que o modelo realmente existe e está dentro do seu escopo de chamada; se o ID do modelo estiver escrito errado ou tiver sido descontinuado, o erro deve ser outro código de erro e não permission_denied, o que ajuda a diferenciar o tipo de problema.
4. Troque por uma Key que você confirmou ter permissão e tente novamente com todos os demais parâmetros idênticos, para verificar se o problema desaparece com a troca da Key.
5. Se, após a verificação, a Key e o modelo estiverem corretos e o 403 ainda se reproduzir de forma consistente, registre o request_id do corpo da resposta e entre em contato com o suporte; não repita a mesma requisição várias vezes sem confirmar a causa.

Exemplo mínimo de verificação

Abaixo, uma requisição que dispara 403 e a nova tentativa após a correção, mostrando a estrutura real de retorno nos dois estados (substitua MODEL_ID pelo modelo que você realmente chama e suspeita não ter permissão):

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "prompt": "a simple test prompt"
  }'

Resposta sem permissão:

{
  "error": {
    "code": "permission_denied",
    "message": "A API Key atual não pode usar este modelo no momento; verifique as permissões ou troque a Key.",
    "request_id": "req_xxxxxxxx",
    "type": "hiapi_error"
  }
}

Após trocar por uma Key com permissão e manter os demais parâmetros inalterados, tente novamente:

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

Note que a estrutura dos dois corpos de resposta é diferente: erros no nível de autenticação/permissão, como o 403, são sempre envolvidos em um objeto error; já os erros gerados depois que a Key passa pela validação de permissão e entra efetivamente na avaliação das regras de negócio específicas (como o 402 de saldo insuficiente) têm um corpo com estrutura plana de code / data / message. Ao ver qual estrutura, dá para julgar aproximadamente se o problema está na camada de autenticação/permissão ou na camada de regras de negócio específicas.

Links internos relacionados

• Gerenciamento de chaves de API
• Documentação de autenticação
• Precificação da HiAPI

FAQ

Qual é exatamente a diferença entre 403 e 401? 401 indica que a Key em si é inválida ou que a requisição não trouxe nenhuma Key — a etapa de autenticação de identidade nem passou. 403 indica que a autenticação de identidade passou (a Key em si é válida), mas essa Key não está autorizada a usar o modelo ou recurso solicitado. A estrutura do corpo de resposta é a mesma nos dois casos (ambos são um objeto envolvido por error.code), e o critério de distinção é o próprio código de status HTTP, não o texto da mensagem de erro.

Depois de trocar a Key, ainda recebo 403; é problema na conta? Primeiro confirme que a nova Key realmente pertence à mesma conta ou projeto com permissão e que, ao copiar e colar, não há espaços extras, quebras de linha ou truncamento. Se, após a verificação, o problema ainda se reproduzir, entre em contato com o suporte informando o request_id do corpo da resposta.

O 403 é por saldo insuficiente? Não. Saldo insuficiente corresponde a outro código de erro (INSUFFICIENT_QUOTA, HTTP 402) e é uma questão diferente de permissão — o 403 só indica "se esta Key tem ou não qualificação para chamar este modelo" e não tem relação com o saldo da conta.

Se aparecer a palavra "permissão" na mensagem de erro, é necessariamente 403? Não necessariamente. O código de erro permission_denied pode aparecer tanto em 401 quanto em 403; não dá para julgar apenas pela palavra-chave do texto, é preciso olhar diretamente o próprio código de status HTTP.