Tutorial

hiapi /v1/tasks tarefa travada ou com timeout: fluxo de diagnóstico e estratégia de retry

Oct 13, 2026

Você enviou uma tarefa para POST https://api.hiapi.ai/v1/tasks, obteve um taskId, mas ao consultar com GET /v1/tasks/{taskId}, o data.status continua parado em queued ou handling por vários minutos — parecendo "travado"; ou então seu loop de polling atingiu o limite que você mesmo definiu sem chegar ao estado terminal, e você reportou timeout. Não se apresse em reenviar: as tarefas do hiapi são assíncronas, "ainda não terminou" e "já falhou" são coisas diferentes; diagnostique com clareza antes de agir para não piorar a situação tentando consertar.

Se você está vendo data.status já como fail, error.code como TASK_TIMEOUT, ou o navegador/proxy lançando um literal HTTP 504 — isso é outro tipo de problema (a tarefa realmente falhou na execução, ou o timeout ocorreu na camada de rede entre você e o hiapi), consulte Solução de problemas de timeout e erro 504 em tarefas HiAPI. Este artigo trata apenas do cenário de "travamento" em que a tarefa demora a chegar ao estado terminal.

Sintomas do problema

Uma tarefa "travada", quando consultada, parece mais ou menos assim (HTTP 200, mas a tarefa ainda em estado não-terminal):

{
  "data": {
    "taskId": "…",
    "status": "queued",
    "output": null,
    "error": null
  }
}

Características-chave: data.status é um dos valores queued (na fila) / handling (em processamento) / archiving (em arquivamento), data.error é null e data.output ainda não tem conteúdo. Isso indica que a tarefa está saudável, apenas ainda não terminou de executar.

As tarefas do hiapi têm apenas dois estados terminais: data.status como success ou fail. Enquanto não for um desses dois, a tarefa não terminou — o "travamento" quase sempre ocorre nesse período não-terminal.

Dois "falsos travamentos" que causam confusão:

A consulta retorna diretamente 404:
```
{"code": 404, "data": null, "message": "task not found"}
```
Isso não é travamento: o taskId está errado, a tarefa não foi criada com sucesso, ou o registro da tarefa expirou — verifique o data.taskId que você recebeu no envio.
Rejeição síncrona no momento do envio (sem obter taskId), por exemplo, model escrito errado:
```
{"code": 400, "data": null, "error_code": "MODEL_UNAVAILABLE", "message": "model not available via /v1/tasks"}
```
Esses são problemas da própria requisição, não de tarefa travada; corrija e reenvie.

Causas comuns (ordenadas por probabilidade de ocorrência)

1. Acúmulo na fila (mais comum)

Quando um modelo (modelo de imagem, modelo de vídeo, ou qualquer modelo de alto poder computacional) está sendo muito chamado, sua tarefa aguardará na fila desse modelo até ser pega por um worker.

Sinal: data.status é queued, data.error é null, e o tempo desde o envio não é longo.
Correção: desacelere o ritmo de polling; consultar a cada 5–10 segundos é suficiente — não fique em loop de 100ms. A maioria das tarefas é pegada em um ou dois minutos.

2. Modelos pesados naturalmente demoram

A tarefa já foi pega (handling/archiving), mas esse modelo já é lento por natureza — vídeos longos, alta resolução, múltiplas imagens de referência aumentam significativamente o tempo de execução.

Sinal: data.status em handling ou archiving, durando vários minutos sem erro.
Correção: dê um limite de polling mais generoso para tarefas pesadas (deixe margem suficiente conforme a capacidade do modelo). Demorar ≠ falhar; não interrompa quando o resultado está quase saindo.

3. Abordagem de polling incorreta (mais facilmente confundida com "travamento")

Muitos "travamentos" são na verdade problemas do cliente: intervalo de polling curto demais que confunde você mesmo, ausência de limite, ou limite curto demais que abandona prematuramente.

Sinal: o data.status no servidor continua avançando normalmente, mas seu loop lançou timeout prematuramente, ou você não está lendo o data.status.
Correção: use intervalo fixo (recomendado 5 segundos) + limite razoável (cerca de 10 minutos para tarefas normais, mais para tarefas pesadas). O timeout deve ser determinado pelo seu loop, não esperando um estado timeout do servidor — o hiapi não tem esse estado.

4. Endpoint de callback inacessível

Se você enviou a tarefa com callback, a tarefa em si pode já estar success, mas o resultado não chega até você, parecendo que "não há movimento".

Sinal: ao consultar ativamente, data.status já é success, data.output tem conteúdo, mas seu endpoint de callback não recebeu nada.
Correção: o endereço de callback deve ser acessível pela internet pública, capaz de receber POST e retornar 2xx em cerca de 10 segundos; caso contrário, use polling. Detalhes em Por que o callback de tarefa do hiapi não disparou.

Passos de correção

Consulte o status primeiro, não reenvie por impulso: GET /v1/tasks/{taskId}, leia data.status e data.error.
Ramo por status:
- queued / handling / archiving → ainda executando, aguarde 5–10 segundos e consulte novamente (causas 1 / 2).
- success → tarefa bem-sucedida, obtenha o resultado em data.output; se você esperava callback e não recebeu → causa 4.
- fail → leia data.error.code e data.error.message; se for TASK_TIMEOUT → veja Guia de timeout e 504.
- 404 task not found → taskId errado ou não criado com sucesso; verifique novamente o data.taskId na resposta de envio.
output tem validade: a URL de download em data.output tem expireAt (cerca de 7 dias); após obtê-la, salve em disco / transfira o quanto antes — não mantenha hotlink de longo prazo.
Confirme que não é problema de autenticação / requisição: execute o exemplo mínimo de verificação abaixo para descartar problemas de key e model id.
Se realmente precisar de retry, use backoff: veja a estratégia de retry na próxima seção; não reenvie o mesmo body repetidamente em loop apertado.

Exemplo mínimo de verificação

Use uma requisição mínima para confirmar que a key e a interface de tarefas estão funcionando. Use o model com id puro (exemplo: gpt-image-2):

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" }
  }'

Envio bem-sucedido retorna algo como {"data":{"taskId":"…","status":"queued"}}. Use o taskId para fazer polling:

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

Se retornar 401 com body {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"…"}} — o problema está na key, não na tarefa. Consulte primeiro Solução de problemas de API Key inválida.
Se o envio for rejeitado com 400 + "error_code":"MODEL_UNAVAILABLE" — é problema do model id. Passe o id puro e consulte Erro "modelo não disponível" do hiapi.

Estratégia de retry que não piora a situação

Backoff exponencial: recomendado 5s → 15s → 45s.
Máximo de 3 tentativas: se a terceira falhar, escale o tratamento (troque de modelo, reduza a configuração ou abra um ticket); não entre em loop infinito.
Cada retry é uma nova tarefa: um POST /v1/tasks é um novo taskId e pode gerar nova cobrança. O hiapi não oferece "reenvio idempotente" garantido publicamente — não espere que reenviar o mesmo body reutilize a tarefa antiga.
Ao encontrar 429, desacelere a taxa de envio, não a de polling: veja Como corrigir erros de limite de taxa (429) do hiapi.

Um exemplo seguro de polling + backoff em Python:

import time, os, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def submit_and_wait(body, poll_interval=5, max_wait=600):
    r = requests.post(BASE, json=body, headers=HEADERS, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + max_wait
    while time.time() < deadline:
        time.sleep(poll_interval)
        data = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
        status = (data.get("data") or {}).get("status")
        if status == "success":
            return data["data"]["output"]
        if status == "fail":
            raise RuntimeError(data["data"].get("error"))
        # queued / handling / archiving → continue aguardando
    raise TimeoutError(f"task {task_id} não chegou ao estado terminal em {max_wait}s")

Observe que a determinação do estado terminal considera apenas success e fail; os demais estados (queued / handling / archiving) continuam aguardando, e o timeout é determinado pelo seu max_wait.

Quando escalar o tratamento

Após 3 tentativas com backoff, todas retornam o mesmo data.error.code → não é instabilidade momentânea; altere a entrada ou troque de modelo.
A tarefa fica muito tempo em queued sem qualquer progresso → verifique no console do hiapi se há notificações da plataforma e abra um ticket com o request_id.
data.status já é success mas o callback nunca chega → pare de depender do callback nesse endpoint e mude para polling.

Links internos relacionados

Solução de problemas de timeout e erro 504 em tarefas HiAPI — quando a tarefa realmente fail com TASK_TIMEOUT, ou quando você vê o 504 literal.
Por que o callback de tarefa do hiapi não disparou — artigo dedicado ao "falso travamento" causado por callback ausente.
Solução de problemas de API Key inválida｜Erro de modelo indisponível｜Erro de limite de taxa 429

FAQ

Q: Quanto tempo conta como "timeout"? Existe uma duração de timeout unificada? A: Não há um número único; depende do modelo; tarefas pesadas (vídeos longos, alta resolução) demoram mais. Além disso, o hiapi não tem estado timeout do servidor — o chamado timeout geralmente é seu loop de polling atingindo o limite que você mesmo definiu. Tarefas que realmente falham por timeout no servidor aparecem como data.status:"fail" + error.code:"TASK_TIMEOUT"; nesse caso, veja Guia de timeout e 504.

Q: A tarefa ficou queued por 30 segundos; devo cancelar e tentar novamente? A: Não. 30 segundos está na faixa normal para qualquer modelo não trivial; espere pelo menos dois minutos antes de considerar retry.

Q: É possível cancelar uma tarefa em execução? A: Geralmente não há suporte a cancelamento; mesmo que fosse possível, a fila / slot de computação normalmente já está ocupado. Deixar terminar e consultar o resultado é mais vantajoso.

Q: A mesma requisição funcionava ontem e hoje travou? A: Na grande maioria, é acúmulo na fila da camada do modelo (causa 1). Troque por um modelo de capacidade similar ou aguarde 5–10 minutos para a fila diminuir e tente novamente.

Q: Todas as tarefas dão timeout; é problema da minha conta? A: Primeiro verifique no console do hiapi se há notificações de nível de conta, depois confirme se você está sendo limitado (veja o guia 429). Se tudo estiver normal e apenas um modelo específico estiver falhando, provavelmente é a fila ou o backend desse modelo, não sua conta.

Q: Reenviar uma tarefa travada / com timeout gera cobrança duplicada? A: Cada POST /v1/tasks é uma nova tarefa cobrada. Tarefas que falharam sem produzir resultado geralmente não são cobradas pela produção, mas a fila / slot de computação pode já estar ocupado. Se custo for preocupação, verifique depois na página de uso.