Como resolver o retorno 402 de saldo insuficiente (INSUFFICIENT_QUOTA) da HiAPI? Causas e passos de correção

Ao chamar a API da HiAPI, ocasionalmente você recebe uma resposta HTTP 402, e o error_code no corpo da resposta é INSUFFICIENT_QUOTA. Isso significa que o saldo de Credits da conta acabou, e não tem relação com a validade da API Key, a correção do formato da requisição ou o acionamento de rate limiting. A tarefa é rejeitada antes de ser criada, portanto nenhuma cobrança é gerada. A correção é quase sempre a mesma: acesse a página de cobrança para adicionar Credits à conta e, em seguida, repita exatamente a mesma requisição que falhou.

Causas comuns

1. O saldo já era 0. Contas novas recebem Credits de bônus de cadastro; quando esse valor e as recargas posteriores se esgotam, qualquer chamada de criação de tarefa retorna 402 até que o saldo volte a ser positivo.
2. Chamadas intensas em curto intervalo consomem o saldo mais rápido do que o esperado. Modelos de vídeo geralmente cobram por segundo de saída; executar vários clipes de vídeo seguidos consome muito mais Credits do que a mesma quantidade de tarefas de imagem, e é fácil o saldo acabar sem que você perceba.
3. Confundir 401 ou 429 com 402. Verifique diretamente o status HTTP e o campo error_code: 401 (error_code semelhante a permission_denied, Key inválida ou desativada) e 429 (error_code: RATE_LIMITED, requisições rápidas demais) parecem "falhas de chamada", mas a forma de correção é totalmente diferente da do 402; misturados nos logs, é fácil investigar na direção errada.

Passos de correção

1. Primeiro confirme o saldo. Abra a página de cobrança do console e veja o saldo atual de Credits; este passo confirma diretamente se o 402 é realmente por problema de saldo.
2. Recarregue a conta. Ainda na página de cobrança, adicione Credits; não há etapa extra de "desbloqueio", e após o saldo ficar positivo a criação de tarefas volta a funcionar imediatamente.
3. Repita exatamente a mesma requisição anterior. Não é necessário alterar nenhum código ou parâmetro. O mesmo prompt, model e outros campos funcionarão diretamente quando o saldo for suficiente; se não souber quanto custa aproximadamente uma chamada de determinado modelo, consulte primeiro a página de preços.
4. Configure alertas de saldo para evitar surpresas na próxima vez. Nas configurações do console há o recurso de alertas de saldo (Balance Alerts); quando o saldo ficar abaixo do limite definido, você receberá uma notificação por e-mail, podendo recarregar antes de realmente esgotar.

Exemplo mínimo de verificação

Com a requisição mínima abaixo é possível confirmar de forma independente que o problema está no saldo da conta, eliminando interferências do modelo ou do próprio SDK:

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a simple test image of a red circle on a white background"
  }'

Com saldo zerado, o retorno é o seguinte:

{
  "code": 402,
  "data": null,
  "error_code": "INSUFFICIENT_QUOTA",
  "message": "insufficient account balance; top up and retry"
}

Após a recarga, repetir a mesma requisição retorna a resposta normal de criação de tarefa:

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

Observe que o campo code é consistente com o status HTTP, error_code é o valor estável usado para decisões de ramificação e data é sempre null quando a criação falha.

Links internos relacionados

• Preços da HiAPI
• Gestão de cobrança e saldo
• Criar tarefa assíncrona (documentação da API)

FAQ

Por que o saldo acabou de repente, sem nenhum aviso antes? Por padrão, você só descobre que o saldo é insuficiente quando uma tarefa realmente falha com 402. Ative os alertas de saldo (Balance Alerts) nas configurações do console; quando o saldo ficar abaixo do limite definido, você receberá um e-mail e poderá recarregar antecipadamente.

O 402 pode interromper uma tarefa que já está em execução? Não. O INSUFFICIENT_QUOTA é retornado na fase de criação da tarefa; nesse momento a tarefa ainda não existe, então não há como interromper uma tarefa em execução; ele apenas bloqueia a criação de novas tarefas.

Requisições que falham com 402 geram cobrança? Não. A verificação de saldo ocorre antes da criação efetiva da tarefa; o 402 significa que a tarefa não foi criada e nenhum Credit foi debitado da conta.

402 e rate limiting (429) são a mesma coisa? Não. O rate limiting retorna 429 com error_code RATE_LIMITED, indicando requisições enviadas rápido demais; o 402 indica saldo de Credits insuficiente na conta, sem relação com a frequência de requisições, e as formas de correção também são diferentes.

Como saber com antecedência antes de o saldo acabar? Abra a página de cobrança do console para ver o saldo atual de Credits e o histórico completo de consumo; lá também é possível definir o limite de alerta de saldo.