Por que uma requisição com falha na HiAPI ainda gera cobrança?

Sintoma do problema

Você envia uma tarefa de geração via POST para https://api.hiapi.ai/v1/tasks e depois faz polling com GET /v1/tasks/:id. O resultado que você recebe é "status": "fail", acompanhado de um objeto error, por exemplo {"code": "TASK_FAILED", "message": "task failed"}. O código de status HTTP dessa própria chamada de polling é o normal 200 — a HiAPI encapsula a informação de falha no corpo JSON, não no código de status. Como essa tarefa de fato passou por queued → handling antes de falhar, é fácil supor que essa tentativa foi cobrada como uma chamada normal. Na verdade, uma tarefa entrar no estado terminal fail não significa que foi cobrada — mas se você consultou o saldo antes do reembolso ser efetivado, aquela reserva feita na criação de fato faz o extrato parecer que houve cobrança.

Causas comuns

1. Confundir a "reserva" com a "cobrança". No momento em que a tarefa é criada, antes mesmo de começar a rodar de verdade, a HiAPI reserva o valor estimado dessa tarefa. Essa reserva aparece imediatamente no seu saldo — mas ainda não é uma cobrança.
2. Consultar o saldo com a tarefa em andamento. Entre queued/handling e o estado terminal, essa reserva fica "pendente", e esse é o comportamento projetado. Apenas o estado terminal (success ou fail) a liquida.
3. Tratar "o downstream realmente rodou mas falhou" e "foi rejeitado na fase de criação" como a mesma coisa. Uma tarefa que chega a status: "fail" (por exemplo, error.code: "TASK_FAILED") foi realmente criada, realmente executou e o downstream falhou — a documentação da HiAPI deixa claro que, depois que a tarefa entra nesse estado terminal, o valor reservado é reembolsado automaticamente na íntegra. Já uma requisição que nunca recebeu um taskId — como um 402 INSUFFICIENT_QUOTA retornado de forma síncrona — foi rejeitada antes de a tarefa existir, então nada foi reservado. Visto de fora, os dois casos parecem "falhas", mas somente o primeiro realmente passou pelo mecanismo de reserva.
4. Idempotency-Key usado de forma incorreta. Repetir a mesma requisição com a mesma key e o mesmo corpo retorna apenas o taskId original, sem criar nem cobrar uma segunda vez. Mas repetir com a mesma key e um corpo diferente retorna diretamente 422 IDEMPOTENCY_KEY_MISMATCH na fase de criação; e repetir com a mesma key enquanto a primeira chamada ainda está sendo processada retorna 409 IDEMPOTENCY_KEY_PROCESSING. Nenhum desses caminhos cria uma tarefa faturável.

Passos de correção

1. Faça polling em GET /v1/tasks/:id e observe diretamente data.status — não tente adivinhar o resultado da cobrança com base em uma captura de tela do saldo em um dado momento. queued, handling e archiving são estados não terminais; somente success e fail são terminais.
2. Se data.status for "fail", esse é um resultado que será reembolsado. Verifique data.error.code (por exemplo, TASK_FAILED) para entender o motivo e consulte o saldo novamente — o reembolso é efetivado automaticamente depois que a tarefa entra nesse estado terminal.
3. Se a própria chamada POST /v1/tasks retornou um código de status não 2xx (400/402/409/415/422) e o corpo não tem taskId, então não há tarefa a reembolsar — porque nenhuma tarefa foi criada nem cobrada. O caso específico de saldo insuficiente se manifesta como error_code: "INSUFFICIENT_QUOTA" na resposta 402.
4. Acesse o painel de faturamento da HiAPI para conferir o par de transações "reserva—reembolso", em vez de olhar apenas o número do saldo em um instante específico.
5. Ao tentar novamente uma tarefa que falhou, use uma nova Idempotency-Key para essa tentativa realmente nova. Não repita usando a key antiga com um corpo diferente (isso aciona 422) nem envie novamente com a mesma key enquanto a primeira requisição ainda está sendo processada (isso aciona 409).
6. Se você confirmar que a tarefa chegou ao estado terminal fail, mas após algum tempo o valor reservado ainda não foi devolvido, isso já está fora do escopo desse mecanismo de reembolso automático — entre em contato com o suporte diretamente, não presuma que vai se resolver sozinho.

Exemplo mínimo de verificação

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": { "prompt": "a minimalist desk setup, studio lighting" }
  }'

Aqui o campo model inclui o sufixo de rota /text-to-image. Até o momento em que este artigo foi escrito, no índice de modelos da HiAPI, o grupo gpt-image-2 só contém entradas com sufixo de rota (/text-to-image, /image-to-image), sem entradas com id puro. Se é necessário ou não incluir o sufixo, e qual sufixo usar, consulte sempre as entradas com availability: "online" nesse índice de modelos em tempo real — não copie o formato de outros modelos ou de documentação antiga.

Depois de obter o taskId retornado, faça polling:

curl -s https://api.hiapi.ai/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Uma tarefa com falha que foi reembolsada se parece com isto:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "gpt-image-2/text-to-image",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_FAILED", "message": "task failed" }
  }
}

Links internos relacionados

• Painel de faturamento da HiAPI
• API unificada de tarefas assíncronas da HiAPI: códigos de erro e descrição de estados
• Tarefa da HiAPI travada ou com timeout: guia de diagnóstico e nova tentativa
• Guia de correção dos erros "model not found" / "model not available" da HiAPI

FAQ

Se uma tarefa de imagem ou vídeo falhar, a HiAPI vai me cobrar? Não. Assim que a tarefa entra no estado terminal fail, o valor reservado na criação é reembolsado automaticamente na íntegra.

Meu saldo diminuiu logo depois que enviei a tarefa, e ela depois falhou. Por que o saldo não voltou? Essa redução foi a reserva feita na criação, não uma cobrança. Ela é liquidada automaticamente depois que a tarefa entra no estado terminal — em fail é devolvida, e somente em success é de fato consumida.

Qual é a diferença entre o erro 402 e uma falha de tarefa? 402 INSUFFICIENT_QUOTA significa que a tarefa nunca chegou a ser criada, então não há nada a reservar nem a reembolsar. Já uma tarefa que recebeu um taskId e depois teve status alterado para "fail" foi realmente criada, realmente executou e então o downstream falhou; a HiAPI devolve automaticamente essa reserva.

Se eu tentar novamente com a mesma Idempotency-Key, serei cobrado duas vezes? Não. Repetir com a mesma key e o mesmo corpo retorna apenas o taskId original, sem criar uma nova tarefa. Se o corpo for alterado sob a mesma key, será retornado diretamente 422 IDEMPOTENCY_KEY_MISMATCH, e também não será criada uma tarefa duplicada.

Onde posso ver os registros de reserva e reembolso? No faturamento e no histórico de transações do painel de faturamento da HiAPI.