Tutorial

hiapi /v1/tasks tareas atascadas o con timeout: flujo de diagnóstico y estrategia de reintentos

Oct 13, 2026

Enviaste una tarea a POST https://api.hiapi.ai/v1/tasks, obtuviste un taskId, pero al consultarla con GET /v1/tasks/{taskId}, data.status sigue en queued o handling durante varios minutos — parece "atascada"; o tu bucle de polling alcanzó el límite que tú mismo configuraste sin llegar al estado final, y entonces reportaste un timeout. No te apresures a reenviar: las tareas de hiapi son asíncronas, "aún no ha terminado" y "ya ha fallado" son dos cosas distintas; diagnostica bien antes de actuar para no empeorar las cosas.

Si lo que ves es que data.status ya es fail, que error.code es TASK_TIMEOUT, o que el navegador/proxy lanza un HTTP 504 literal — eso es otro tipo de problema (la tarea realmente falló al ejecutarse, o el timeout ocurrió en la capa de red entre tú y hiapi); consulta Solución de problemas de timeout y errores 504 en tareas de HiAPI. Este artículo solo trata el escenario de "atascamiento" en el que la tarea tarda mucho en llegar al estado final.

Síntomas del problema

Una tarea "atascada", al consultarla, se ve aproximadamente así (HTTP 200, pero la tarea sigue en estado no final):

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

Características clave: data.status es uno de queued (en cola) / handling (procesando) / archiving (archivando), data.error es null y data.output aún no tiene contenido. Esto indica que la tarea está sana, simplemente aún no ha terminado de ejecutarse.

Las tareas de hiapi solo tienen dos estados finales: data.status es success o fail. Mientras no sea ninguno de estos dos, significa que la tarea no ha terminado — el "atascamiento" casi siempre ocurre en este tramo de estados no finales.

Dos "falsos atascamientos" que suelen confundirse:

La consulta devuelve directamente 404:
```
{"code": 404, "data": null, "message": "task not found"}
```
Esto no es un atascamiento: el taskId está mal escrito, la tarea no se creó correctamente, o el registro de la tarea ya expiró — verifica el data.taskId que obtuviste al enviarla.
Rechazo síncrono en el momento del envío (nunca obtuviste un taskId), por ejemplo por un model mal escrito:
```
{"code": 400, "data": null, "error_code": "MODEL_UNAVAILABLE", "message": "model not available via /v1/tasks"}
```
Estos son problemas de la propia solicitud, no tareas atascadas; corrígelo y vuelve a enviar.

Causas comunes (ordenadas por probabilidad de ocurrencia)

1. Acumulación en la cola (la más común)

Cuando un modelo (modelo de imagen, modelo de vídeo, o cualquier modelo con alta carga de cómputo) está siendo llamado masivamente, tu tarea espera en la cola de ese modelo a que un worker la recoja.

Señal: data.status es queued, data.error es null, y no ha pasado mucho tiempo desde el envío.
Solución: reduce el ritmo de polling, consultar cada 5–10 segundos es suficiente; no hagas espera activa cada 100 ms. La mayoría de las tareas se recogen en uno o dos minutos.

2. Los modelos pesados tardan por naturaleza

La tarea ya fue recogida (handling/archiving), pero este modelo tarda inherentemente en completar una ejecución — vídeos largos, alta resolución y múltiples imágenes de referencia alargan significativamente el tiempo.

Señal: data.status está en handling o archiving, persiste varios minutos pero no hay error.
Solución: da un límite de polling más amplio a las tareas pesadas (deja margen suficiente según la capacidad del modelo). Tardar mucho ≠ fallar; no cortes tú mismo justo cuando está a punto de dar resultado.

3. Postura de polling incorrecta (la que más fácilmente se malinterpreta como "atascamiento")

Muchos "atascamientos" son en realidad problemas del cliente: intervalo de polling demasiado corto que te confunde, sin límite establecido, o límite demasiado corto que abandona prematuramente.

Señal: el data.status del servidor avanza normalmente, pero tu bucle lanzó un timeout antes de tiempo, o simplemente no estás leyendo data.status.
Solución: usa un intervalo fijo (se recomienda 5 segundos) + un límite razonable (unas 10 minutos para tareas normales, más para tareas pesadas). El timeout debe determinarlo tu bucle, no esperar un estado timeout del servidor — hiapi no tiene ese estado.

4. Endpoint de callback inaccesible

Si incluiste un callback al enviar la tarea, es posible que la tarea ya esté en success, pero el resultado no llega a tu lado, por lo que parece que "no hay movimiento".

Señal: al consultar activamente, data.status ya es success y data.output tiene contenido, pero tu endpoint de callback no recibió nada.
Solución: la URL de callback debe ser accesible públicamente, poder recibir POST y devolver 2xx en unos 10 segundos; de lo contrario, cambia a polling. Para más detalles, consulta Por qué no se dispara el callback de tareas de hiapi.

Pasos de solución

Consulta primero el estado una vez, no reenvíes por intuición: GET /v1/tasks/{taskId}, lee data.status y data.error.
Ramifica según el estado:
- queued / handling / archiving → sigue ejecutándose, espera 5–10 segundos y vuelve a consultar (causas 1 / 2).
- success → tarea exitosa, obtén el resultado de data.output; si esperabas un callback y no lo recibiste → causa 4.
- fail → lee data.error.code y data.error.message; si es TASK_TIMEOUT → consulta la guía de timeout y 504.
- 404 task not found → el taskId está mal o no se creó correctamente; vuelve a verificar el data.taskId de la respuesta del envío.
output tiene caducidad: las URLs de descarga en data.output llevan expireAt (unos 7 días); en cuanto las obtengas, guárdalas en disco / transfiérelas cuanto antes, no mantengas enlaces directos a largo plazo.
Confirma que no es un problema de autenticación / solicitud: ejecuta primero el ejemplo mínimo de verificación a continuación para descartar problemas con la key y el model id.
Si realmente hay que reintentar, usa backoff: consulta la estrategia de reintentos de la siguiente sección; no reenvíes repetidamente el mismo body en un bucle apretado.

Ejemplo mínimo de verificación

Usa una solicitud mínima para confirmar que la key y la propia interfaz de tareas funcionan. Usa el id desnudo para el model (ejemplo: 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" }
  }'

Si el envío es exitoso, obtendrás una respuesta similar a {"data":{"taskId":"…","status":"queued"}}. Usa el taskId para hacer polling:

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

Si devuelve 401 con body {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"…"}} — el problema está en la key, no en la tarea. Consulta primero Solución de problemas de API Key inválida.
Si el envío es rechazado con 400 + "error_code":"MODEL_UNAVAILABLE" — es un problema del model id. Pasa el id desnudo y consulta Error "modelo no disponible" de hiapi.

Estrategia de reintentos que no empeora las cosas

Backoff exponencial: se recomienda 5s → 15s → 45s.
Máximo 3 intentos: si el tercero también falla, escala el manejo (cambia de modelo, reduce la configuración, o abre un ticket); no hagas bucles infinitos.
Cada reintento es una tarea nueva: un POST /v1/tasks es un nuevo taskId y puede generar nueva facturación. hiapi no ofrece un "reenvío idempotente" garantizado públicamente — no esperes que reenviar el mismo body reutilice la tarea anterior.
Cuando encuentres 429, lo que debes reducir es la tasa de envío, no la de polling: consulta Cómo solucionar el error de límite de tasa (429) de hiapi.

Un ejemplo seguro de polling + backoff en 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 → sigue esperando
    raise TimeoutError(f"la tarea {task_id} no alcanzó el estado final en {max_wait}s")

Ten en cuenta que la determinación del estado final solo reconoce success y fail; los demás estados (queued / handling / archiving) siguen esperando sin excepción, y el timeout lo decide tu max_wait.

Cuándo escalar el manejo

Reintentas con backoff 3 veces y cada vez obtienes el mismo data.error.code → no es una fluctuación transitoria; cambia la entrada o cambia de modelo.
La tarea permanece mucho tiempo en queued sin ningún progreso → revisa en la consola de hiapi si hay notificaciones de la plataforma y abre un ticket con el request_id.
data.status ya es success pero el callback nunca llega → deja de depender del callback en ese endpoint y cambia a polling.

Enlaces internos relacionados

Solución de problemas de timeout y errores 504 en tareas de HiAPI — consulta este artículo cuando la tarea realmente fail con TASK_TIMEOUT, o cuando veas un 504 literal.
Por qué no se dispara el callback de tareas de hiapi — artículo dedicado al "falso atascamiento" causado por la ausencia del callback.
Solución de problemas de API Key inválida｜Error de modelo no disponible｜Error de límite de tasa 429

FAQ

P: ¿Cuánto tiempo cuenta como "timeout"? ¿Hay una duración de timeout unificada? R: No hay una cifra unificada, depende del modelo; las tareas pesadas (vídeos largos, alta resolución) tardan más. Además, hiapi no tiene un estado timeout del lado del servidor — lo que llamamos timeout suele ser que tu bucle de polling alcanzó el límite que tú mismo estableciste. Una tarea que realmente falla por timeout en el servidor será data.status:"fail" + error.code:"TASK_TIMEOUT"; para ese caso consulta la guía de timeout y 504.

P: La tarea lleva 30 segundos en queued, ¿debo cancelarla y reintentar? R: No. 30 segundos está dentro de lo normal para cualquier modelo no trivial; espera al menos dos minutos antes de considerar un reintento.

P: ¿Se puede cancelar una tarea en ejecución? R: Generalmente no se admite cancelación; incluso si se pudiera, la cola / el slot de cómputo normalmente ya está ocupado. Dejarla terminar y consultar el resultado es más rentable.

P: La misma solicitud funcionaba ayer, pero hoy se atasca. R: En la gran mayoría de los casos es acumulación en la cola de la capa del modelo (causa 1). Cambia a un modelo de capacidad similar, o espera 5–10 minutos a que la cola disminuya y vuelve a intentarlo.

P: Todas las tareas dan timeout, ¿es un problema de mi cuenta? R: Primero revisa en la consola de hiapi si hay notificaciones a nivel de cuenta, y luego confirma si estás siendo limitado por tasa (consulta la guía de 429). Si todo está normal y solo falla un modelo en concreto, lo más probable es que sea la cola o el backend de ese modelo, no tu cuenta.

P: ¿Reintentar una tarea atascada / con timeout genera doble facturación? R: Cada POST /v1/tasks es una nueva tarea facturable. Las tareas fallidas que no producen resultado normalmente no cobran la producción, pero la cola / el slot de cómputo pueden haberse ocupado. Si te preocupa el coste, verifica después en la página de uso.

Etiquetashiapi Solución de problemas Tareas asíncronas retry Solución de problemas Tarea asíncrona Reintentar