Tiempo de espera agotado de tareas de HiAPI y error 504: guía de diagnóstico y solución

En la respuesta que devuelve GET /v1/tasks/{id}, las tareas de HiAPI a veces presentan "status": "fail", "error": {"code": "TASK_TIMEOUT", "message": "Task timed out"} — tenga en cuenta que el código de estado HTTP de esta respuesta en sí es 200. Este es el estado de fallo real documentado por HiAPI, que significa que la tarea ya comenzó a ejecutarse pero no pudo completarse dentro del presupuesto de tiempo interno. Si lo que ve no es este tipo de JSON, sino que el cliente lanza directamente un 504 Gateway Timeout de HTTP sin más, entonces no es la API de HiAPI la que lo devuelve: 504 no aparece en ninguna lista de códigos de estado documentada por HiAPI. Este artículo trata ambos casos por separado: cómo leer y cómo solucionar el verdadero TASK_TIMEOUT; y de dónde surge realmente el 504.

Qué aspecto tiene exactamente el error

El flujo de tareas de HiAPI es asíncrono: POST /v1/tasks devuelve inmediatamente un taskId, y después se consulta GET /v1/tasks/{id} mediante polling para obtener el resultado. El campo error solo aparece cuando status alcanza un estado terminal. Un verdadero tiempo de espera agotado tiene este aspecto:

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

Tenga en cuenta que el código de estado HTTP de esta respuesta es 200: la solicitud de polling en sí tuvo éxito; lo que falló es la tarea, y los detalles del fallo están en data.error. Esto es distinto de un fallo síncrono en la fase de creación (por ejemplo, saldo insuficiente es 402, cuerpo de solicitud incorrecto es 400); ese tipo de errores se devuelven inmediatamente en la llamada inicial POST /v1/tasks, cuando la tarea aún no se ha creado. TASK_TIMEOUT solo ocurre en una tarea que ya se creó correctamente.

Y 504, en la mayoría de los casos, no es un cuerpo de respuesta en absoluto: es un código de estado que un proxy, un balanceador de carga o ciertas bibliotecas cliente HTTP emiten por su cuenta cuando dejan de esperar cualquier respuesta. Los códigos de estado HTTP documentados por HiAPI son 200, 400, 402, 404, 409, 415, 422, 503 — entre ellos no hay 504. Si lo que ve es en realidad 401, ese es otro problema (API Key no válida o deshabilitada, no un tiempo de espera agotado) y queda fuera del alcance de este artículo.

Causas comunes (ordenadas por probabilidad de aparición)

1. Tiempo de espera agotado real a nivel de tarea. El modelo recibió la tarea, pero no pudo completarla dentro del presupuesto de tiempo interno. Este es exactamente el escenario TASK_TIMEOUT mostrado arriba, más frecuente en tareas más pesadas: mayor duración de vídeo, mayor resolución o una sobrecarga temporal del propio modelo.
2. El 504 proviene de fuera de HiAPI. La gran mayoría de los informes de "504" son en realidad el read timeout del propio cliente (la biblioteca HTTP se rinde porque no puede esperar), o bien un proxy corporativo, VPN o balanceador de carga entre usted y api.hiapi.ai que corta la conexión según su propia configuración de tiempo de espera. Dado que HiAPI nunca devuelve 504, esto es un problema de configuración del lado del cliente o de la red, no un fallo de HiAPI.
3. La tarea sigue ejecutándose y se malinterpreta como tiempo de espera agotado. queued, handling y archiving son estados no terminales; en ese momento el campo error no existe en absoluto. Ver una vez en el polling que el estado no es success no equivale a un tiempo de espera agotado.

Pasos de solución

1. Obtenga la tarea por taskId y lea directamente status y error.code. No adivine la causa a partir de un mensaje de excepción genérico en el código del cliente: llame a GET /v1/tasks/{id} y observe el propio cuerpo de la respuesta.
2. Si status es "fail" y error.code es "TASK_TIMEOUT": reintente. La solución documentada es así de simple: vuelva a enviar la tarea con una nueva llamada POST /v1/tasks (obtendrá un nuevo taskId); no hace falta cambiar de cuenta ni de Key.
3. Si la tarea en sí es pesada, revise primero la entrada. Una mayor duración de vídeo, una mayor resolución o un prompt muy grande/complejo acercan al modelo a su límite de presupuesto de tiempo. Si la misma configuración agota el tiempo repetidamente, pruebe con menor resolución/duración o cambie de modelo.
4. Si lo que ve es en realidad un 504 sin más (sin cuerpo de respuesta JSON con error.code), el problema está fuera de HiAPI. Revise el read timeout configurado en su propio cliente HTTP o SDK: muchos valores predeterminados son demasiado cortos (10-30 segundos) y, en un flujo asíncrono, una solicitud larga no debería bloquearse de esa forma, sino que debería consultarse por separado mediante polling. Compruebe también si pasa por un proxy corporativo, una puerta de enlace VPN o un balanceador de carga que puedan cortar la conexión según su propia configuración de tiempo de espera, sin relación alguna con HiAPI.
5. Si status sigue siendo queued, handling o archiving, no reintente todavía. Nada ha fallado realmente. Para un diagnóstico más completo, consulte la guía de diagnóstico de tareas bloqueadas/tiempo de espera agotado de hiapi (en inglés).

Ejemplo mínimo de verificación

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

Esto devuelve inmediatamente un taskId:

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

Después, consulte mediante polling:

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

Una tarea normal acabará devolviendo "status": "success" y el resultado de salida. Una tarea que realmente agote el tiempo de espera devolverá la estructura TASK_TIMEOUT mostrada antes. Si lo que obtiene es un 504 a nivel de conexión, sin ningún cuerpo de respuesta JSON, eso indica que la respuesta no pudo llegar de vuelta desde la API de HiAPI: siga los pasos anteriores para revisar la configuración de tiempo de espera de su cliente y la ruta de red, en lugar de sospechar que su cuenta tiene un problema.

Enlaces internos relacionados

• Consola de HiAPI
• Crear tarea asíncrona (documentación de la API)
• guía de diagnóstico de tareas bloqueadas/tiempo de espera agotado de hiapi (en inglés)

FAQ

¿Son lo mismo el TASK_TIMEOUT de HiAPI y el HTTP 504 Gateway Timeout? No. TASK_TIMEOUT es un código de error documentado por HiAPI que aparece dentro de una respuesta normal 200 y representa que el status de la propia tarea pasó a fail, es decir, que la tarea agotó su tiempo de ejecución interna. 504 es un código de estado HTTP genérico que ciertos proxies, balanceadores de carga y bibliotecas cliente HTTP devuelven cuando dejan de esperar una respuesta; la API de HiAPI no documenta ni devuelve 504 en absoluto, por lo que el 504 literal que ve proviene necesariamente de algún punto entre usted y HiAPI, o de su propio cliente, que dejó de esperar; no es un fallo del servidor de HiAPI.

¿Qué debo hacer si encuentro TASK_TIMEOUT? Basta con enviar una nueva tarea. La solución documentada para TASK_TIMEOUT es reintentar; no hay pasos de desbloqueo independientes y, si la misma entrada no agota el tiempo repetidamente, tampoco es necesario cambiar el prompt ni los parámetros.

¿Se me cobrará dos veces si reintento una tarea que agotó el tiempo de espera? La tabla de códigos de error documentada por HiAPI no lo especifica claramente. Si esto es importante para usted, consulte el registro de uso en la consola con ese taskId concreto para confirmarlo; no lo determine a partir de suposiciones.

Mi cliente HTTP lanzó una excepción de tiempo de espera agotado, no un TASK_TIMEOUT en formato JSON. ¿Es lo mismo? No. El tiempo de espera agotado del propio cliente (por ejemplo, ReadTimeout de la biblioteca HTTP, o un 504 devuelto por un proxy corporativo) significa que su conexión se rindió por sí misma antes de recibir cualquier respuesta de HiAPI, lo cual no implica que la tarea en sí haya fallado. Dado que /v1/tasks es asíncrono, la solución habitual es aumentar el read timeout del cliente (o simplemente no bloquearse esperando en el POST inicial) y consultar por separado GET /v1/tasks/{id} mediante polling hasta ver un estado terminal.

La tarea lleva varios minutos en queued o handling y no hay error. ¿Cuenta esto como tiempo de espera agotado? Todavía no. queued, handling y archiving son estados no terminales; el campo error solo aparece cuando status pasa a fail. Si la tarea realmente no converge nunca, puede consultar en la guía de diagnóstico de tareas bloqueadas/tiempo de espera agotado de hiapi (en inglés) el desglose completo de causas en curso, como la acumulación en cola.