Tempo limite de tarefas e erro 504 na HiAPI: guia de diagnóstico e correção

As tarefas da HiAPI, na resposta de GET /v1/tasks/{id}, às vezes apresentam "status": "fail", "error": {"code": "TASK_TIMEOUT", "message": "Task timed out"} — observe que o código de status HTTP dessa própria resposta é 200; este é o estado de falha real documentado pela HiAPI, que significa que a tarefa começou a ser executada, mas não conseguiu terminar dentro do orçamento de tempo interno. Se o que você vê não é esse JSON, mas sim um 504 Gateway Timeout HTTP puro lançado diretamente pelo cliente, então ele não é retornado pela API da HiAPI: 504 não está em nenhuma lista de códigos de status documentada pela HiAPI. Este artigo trata os dois casos separadamente: como ler e corrigir um TASK_TIMEOUT real; e de onde exatamente vem o 504.

Como o erro realmente se parece

O fluxo de tarefas da HiAPI é assíncrono: POST /v1/tasks retorna imediatamente um taskId, e depois você consulta GET /v1/tasks/{id} para obter o resultado por polling. O campo error só aparece quando status atinge um estado terminal. Um timeout real se parece com isto:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-xxxxxxxx",
    "model": "gpt-image-2",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_TIMEOUT", "message": "Task timed out" }
  }
}

Observe que o código de status HTTP dessa resposta é 200 — a requisição de polling em si foi bem-sucedida; o que falhou foi a tarefa, e os detalhes da falha estão em data.error. Isso é diferente de uma falha síncrona na fase de criação (por exemplo, saldo insuficiente é 402, corpo da requisição inválido é 400); esse tipo de erro é retornado imediatamente na chamada inicial POST /v1/tasks, quando a tarefa ainda nem foi criada. O TASK_TIMEOUT só ocorre em uma tarefa que já foi criada com sucesso.

Já o 504, na maioria dos casos, não é um corpo de resposta; é um código de status que proxies, load balancers ou algumas bibliotecas de cliente HTTP emitem por conta própria quando desistem de esperar qualquer resposta. Os códigos de status HTTP documentados pela HiAPI são 200, 400, 402, 404, 409, 415, 422, 503 — entre eles não há 504. Se o que você vê é na verdade 401, trata-se de outro problema (API Key inválida ou desativada, não timeout), fora do escopo deste artigo.

Causas comuns (ordenadas por probabilidade)

1. Timeout real no nível da tarefa. O modelo recebeu a tarefa, mas não conseguiu concluí-la dentro do orçamento de tempo interno. É exatamente o cenário TASK_TIMEOUT mostrado acima, mais comum em tarefas mais pesadas — durações de vídeo maiores, resoluções mais altas ou sobrecarga temporária do próprio modelo.
2. 504 vindo de fora da HiAPI. A grande maioria dos relatos de "504" é, na verdade, o read timeout do próprio cliente (a biblioteca HTTP desiste por impaciência) ou um proxy corporativo, VPN ou load balancer entre você e api.hiapi.ai que corta a conexão segundo sua própria configuração de timeout. Como a HiAPI nunca retorna 504, trata-se de um problema de configuração do lado do cliente ou da rede, não de uma falha da HiAPI.
3. Tarefa ainda em execução, interpretada erroneamente como timeout. queued, handling e archiving são estados não terminais; nesse momento o campo error simplesmente não existe. Ver um status diferente de success em uma única consulta não significa timeout.

Passos de correção

1. Busque a tarefa pelo taskId e leia diretamente status e error.code. Não tente adivinhar a causa a partir de uma mensagem de exceção genérica no código do cliente — chame GET /v1/tasks/{id} e observe o próprio corpo da resposta.
2. Se status for "fail" e error.code for "TASK_TIMEOUT": tente novamente. A correção documentada é exatamente essa — reenvie com uma nova chamada POST /v1/tasks (obtendo um novo taskId); não é necessário trocar de conta ou de Key.
3. Se a tarefa for pesada, verifique primeiro a entrada. Durações de vídeo maiores, resoluções mais altas ou prompts muito grandes/complexos aproximam o modelo do limite do seu orçamento de tempo. Se a mesma configuração atingir timeout repetidamente, experimente resolução/duração menores ou troque de modelo.
4. Se o que você vê é um 504 puro (sem corpo JSON com error.code), o problema está fora da HiAPI. Verifique o read timeout configurado no seu cliente HTTP ou SDK — muitos valores padrão são curtos demais (10-30 segundos); em um fluxo assíncrono, uma requisição longa não deveria ficar bloqueada, e sim ser feita por polling separado. Confirme também se você passa por um proxy corporativo, gateway VPN ou load balancer, que podem cortar a conexão segundo seus próprios timeouts, sem qualquer relação com a HiAPI.
5. Se status ainda for queued, handling ou archiving, não tente novamente ainda. Nada realmente falhou. Para um diagnóstico mais completo, consulte o guia de diagnóstico de tarefas travadas/timeout da hiapi (em inglês).

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" \
  -d '{
    "model": "gpt-image-2",
    "input": {
      "prompt": "a single red apple on a white background, studio lighting"
    }
  }'

Isso retorna imediatamente um taskId:

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

Depois, consulte por polling:

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

Uma tarefa normal acabará retornando "status": "success" e o resultado da saída. Uma tarefa que realmente atingiu timeout retornará a estrutura TASK_TIMEOUT mostrada anteriormente. Se o que você recebe é um 504 em nível de conexão, sem nenhum corpo de resposta JSON, isso indica que a resposta não conseguiu sair da API da HiAPI até você — siga os passos acima para verificar as configurações de timeout do seu cliente e o caminho de rede, em vez de suspeitar que há algum problema na conta.

Links internos relacionados

• Console da HiAPI
• Criar tarefa assíncrona (documentação da API)
• guia de diagnóstico de tarefas travadas/timeout da hiapi (em inglês)

FAQ

O TASK_TIMEOUT da HiAPI e o HTTP 504 Gateway Timeout são a mesma coisa? Não. TASK_TIMEOUT é um código de erro documentado pela HiAPI, que aparece em uma resposta normal 200 e representa que o status da própria tarefa passou para fail, ou seja, a tarefa atingiu timeout internamente. 504 é um código de status HTTP genérico que alguns proxies, load balancers e bibliotecas de cliente HTTP retornam quando desistem de esperar a resposta; a API da HiAPI não documenta nem retorna 504, então o 504 literal que você vê é necessariamente algum elo entre você e a HiAPI, ou o seu próprio cliente, que desistiu de esperar — não é uma falha do servidor da HiAPI.

O que fazer ao encontrar TASK_TIMEOUT? Basta reenviar uma nova tarefa. A correção documentada para TASK_TIMEOUT é tentar novamente; não há um passo separado de desbloqueio, e se a mesma entrada não atingir timeout repetidamente, também não é necessário alterar o prompt ou os parâmetros.

Tentar novamente uma tarefa que atingiu timeout gera cobrança dupla? A tabela de códigos de erro documentada pela HiAPI não diz isso explicitamente. Se isso for importante para você, consulte o registro de uso no console com este taskId específico para confirmar; não decida por suposição.

Meu cliente HTTP lançou uma exceção de timeout, não um TASK_TIMEOUT em formato JSON; é a mesma coisa? Não. O timeout do próprio cliente (por exemplo, um ReadTimeout da biblioteca HTTP, ou um 504 retornado por um proxy corporativo) significa que sua conexão desistiu antes de obter qualquer resposta da HiAPI, o que não indica que a tarefa em si falhou. Como /v1/tasks é assíncrono, a correção comum é aumentar o read timeout do cliente (ou simplesmente não bloquear à espera no POST inicial) e fazer polling separado em GET /v1/tasks/{id} até ver um estado terminal.

A tarefa está em queued ou handling há vários minutos, sem erro; isso conta como timeout? Ainda não. queued, handling e archiving são estados não terminais; o campo error só aparece quando status passa para fail. Se a tarefa realmente nunca convergir, consulte o guia de diagnóstico de tarefas travadas/timeout da hiapi (em inglês), que traz uma análise completa de causas em andamento, como acúmulo na fila.