Error 502 / 503 de HiAPI en el upstream: causas y cómo solucionarlo

Llamas a POST https://api.hiapi.ai/v1/tasks (o consultas GET /v1/tasks/{id}) y, en lugar de recibir el habitual 200 con taskId, obtienes 502 Bad Gateway o 503 Service Unavailable. Ambos son respuestas 5xx, lo que indica que el problema está en el servidor o en el transporte, no en tu solicitud: no has enviado parámetros incorrectos, una clave incorrecta ni un payload mal formado. El 503 es la señal de "plataforma temporalmente no disponible" documentada en la documentación de HiAPI, que te indica que debes reintentar; el 502, en cambio, es una respuesta a nivel de gateway generada en algún punto de la cadena. Esta guía explica cómo confirmarlo, cómo reintentar de forma segura sin duplicar trabajo y cómo distinguir los 502/503 de los tiempos de espera 504 y de los resultados TASK_FAILED.

Cómo se ven realmente un 502 o un 503

Verás una de las siguientes líneas de estado HTTP en lugar del 200 normal:

• 503 Service Unavailable — este sí está documentado. La documentación de la API asíncrona de HiAPI enumera el 503 como "plataforma temporalmente no disponible; reintenta más tarde con retroceso exponencial", con el código de negocio correspondiente TEMPORARILY_UNAVAILABLE ("Servicio de generación temporalmente no disponible. Reintenta más tarde; si el problema persiste, contacta con soporte."). Los errores síncronos de HiAPI usan un sobre JSON plano — en la documentación, el caso 400 es {"code": 400, "message": "...", "data": null, "error_code": "INVALID_REQUEST"} —, por lo que un 503 devuelto por la API también debería usar el mismo sobre con error_code: "TEMPORARILY_UNAVAILABLE".
• 502 Bad Gateway — este no figura entre los códigos de estado documentados de HiAPI. En HTTP estándar, un 502 significa que un gateway o proxy recibió una respuesta no válida o vacía del siguiente salto al que intentó acceder. Por tanto, el 502 que recibes lo genera un gateway en la cadena —posiblemente la capa de edge/CDN, el balanceador de carga o un proxy de tu propia red—, no la aplicación de HiAPI devolviendo su sobre JSON habitual. El cuerpo de la respuesta suele ser una página breve de gateway en HTML o texto plano, y ese cuerpo no JSON es en sí mismo una señal: indica una condición de transporte/gateway, no un error de aplicación con un payload fijo y documentado.

En cualquier caso, el estado es 5xx: el problema está en el servidor o en el transporte, no en tu solicitud. Esto es lo contrario de 4xx —400 (parámetros incorrectos), 401 (clave incorrecta; HiAPI devuelve el anidado {"error": {"code": "permission_denied", "type": "hiapi_error", "request_id": "..."}}) o 402 (saldo insuficiente)—, que requieren que cambies algo de tu lado para solucionarlo. Los 502/503 no se arreglan modificando el payload.

Causas habituales (ordenadas de mayor a menor probabilidad)

1. Sobrecarga temporal de la plataforma o ventana de mantenimiento → 503 TEMPORARILY_UNAVAILABLE. Es una situación esperada y documentada. Se recupera por sí sola; reintentar con retroceso acabará funcionando.
2. Un fallo momentáneo de algún gateway o proxy en la cadena → 502. La capa de edge/CDN, el balanceador de carga o un proxy de tu propia red no lograron reenviar la respuesta durante un instante. También es temporal.
3. Un pico de tráfico que activó una limitación. Bajo carga alta, es posible que veas en su lugar 429 RATE_LIMITED ("Reintenta más tarde; evita reenviar la misma solicitud de inmediato"). Si el estado es 429, la solución es reducir la tasa de envío, no reintentar con más fuerza.
4. El backend del modelo solicitado no está disponible temporalmente. HiAPI lo registra a nivel de tarea como MODEL_UNAVAILABLE ("Reintenta más tarde o cambia de modelo"); un fallo breve a nivel de plataforma en el servicio que atiende ese modelo también puede manifestarse como 503.
5. No es un error de clave, un cuerpo de solicitud mal formado ni saldo insuficiente. Esos son 401 / 400 / 402 respectivamente, y ninguno se manifiesta como 502 o 503.

Cómo solucionarlo en orden

1. Confirma que es 5xx y no 4xx. Mira primero el código de estado. 502/503 pertenecen al lado del servidor/transporte; 400, 401, 402, 404, 409, 415, 422 y 429 pertenecen a tu lado. Si realmente es 502/503, no empieces a reescribir el cuerpo de la solicitud: eso solo ayuda con los 4xx.
2. Reintenta con retroceso exponencial y jitter. La documentación exige explícitamente retroceso exponencial para el 503. Un patrón de cliente seguro es empezar en torno a 1 segundo, duplicar en cada intento (2 s, 4 s, 8 s…), con un límite de unos 30-60 s, y añadir jitter aleatorio para que una multitud de clientes no reintente sincronizadamente. Estos intervalos son patrones de cliente recomendados, no garantías de tiempos publicadas por HiAPI.
3. Haz que el envío sea idempotente. Establece la cabecera Idempotency-Key en POST /v1/tasks (cualquier cadena UTF-8, de hasta 255 bytes). Si un 502/503 te deja con la duda de si la tarea se creó realmente, reintentar con la misma clave es seguro: la misma clave + el mismo cuerpo de solicitud devolverán el taskId original con la cabecera de respuesta Idempotent-Replay: true, sin crear una segunda tarea ni generar un segundo cargo. La clave está limitada al ámbito de la cuenta y caduca a las 24 horas. El contrato completo está en la documentación de Unified Async API.
4. No vuelvas a hacer POST a ciegas sin la clave. Si enviaste sin Idempotency-Key y recibiste un 502/503, es posible que ya hayas creado una tarea que no ves: no tienes un taskId que consultar, así que un reintento ingenuo corre el riesgo de duplicar trabajo y duplicar cargos. Añade la clave antes de reintentar a cualquier escala.
5. Si el 502/503 ocurre durante el sondeo, simplemente sigue sondeando. Un 5xx devuelto por GET /v1/tasks/{id} no cambia el estado de la tarea. Los estados terminales (success / fail) quedan fijados en cuanto se alcanzan y nunca pasan de uno a otro, así que basta con volver a sondear tras el retroceso. Como alternativa, registra callback.url para recibir una notificación en el estado terminal en lugar de sondear a través de 5xx temporales; la entrega es al menos una vez, así que deduplica por taskId.
6. Distínguelo de un fallo a nivel de tarea. Si en cambio recibes HTTP 200 con "status": "fail", eso no es un 502/503: la tarea se aceptó, se ejecutó y falló. Trata TASK_FAILED ("Reintenta una vez; si el problema persiste, contacta con soporte") o TASK_TIMEOUT ("Reintenta la tarea") según corresponda, en lugar de hacer un reintento ciego de gateway.
7. Si persiste, escala en lugar de insistir. Si el 502/503 sigue apareciendo tras varios reintentos con retroceso durante varios minutos, trátalo como un incidente temporal de la plataforma, no como algo que se resuelva a base de fuerza bruta. Deja de reintentar agresivamente y contacta con soporte adjuntando el request_id si el cuerpo del error lo incluye. Puedes comprobar que tu cuenta y tu conectividad funcionan correctamente desde la consola de HiAPI.

Comparación entre 502 / 503, 504 y TASK_FAILED

Es fácil confundirlos, porque todos implican que "no se devolvió limpiamente", pero requieren tratamientos distintos:

Respuesta	Código de estado HTTP	Origen	¿Se cobra la tarea?	Qué hacer
503 Service Unavailable	503 (documentado)	Plataforma de HiAPI — temporalmente no disponible o sobrecargada	No se puede determinar por la respuesta; la tarea puede existir ya	Reintenta con retroceso y la misma Idempotency-Key
502 Bad Gateway	502 (no está en la documentación de HiAPI)	Gateway/proxy en la cadena (edge, balanceador de carga o tu propio proxy)	No se puede determinar por la respuesta	Reintento idempotente con retroceso; si solo ocurre desde tu red, sospecha de un proxy de tu lado
504 Gateway Timeout	504 (no está en la documentación de HiAPI)	Un gateway o proxy en la cadena que dejó de esperar (la documentación de HiAPI no enumera el 504)	No se puede determinar por la respuesta	Igual que el 502; HiAPI informa de sus propios tiempos de espera como TASK_TIMEOUT
TASK_TIMEOUT	200 + "status": "fail"	HiAPI — la tarea se ejecutó pero superó el presupuesto de tiempo	No (importe reservado reembolsado)	Reintenta la tarea como una nueva solicitud
TASK_FAILED	200 + "status": "fail"	HiAPI — la tarea se aceptó, se ejecutó y luego falló	No (importe reservado reembolsado)	Reintenta una vez y luego lee error.message
429 RATE_LIMITED	429	HiAPI — enviaste demasiado rápido	Sin tarea	Retroceso; no reenvíes de inmediato
400 / 401 / 402	4xx	HiAPI — lado del cliente (cuerpo/clave/saldo incorrectos)	No	Corrige la solicitud, la clave o el saldo; reintentar no sirve de nada

Regla de un vistazo: 502/503/504 son errores de transporte HTTP y no llevan ningún resultado de tarea; TASK_FAILED / TASK_TIMEOUT, en cambio, llegan como HTTP 200 con "status": "fail" y un objeto error. Lo primero significa "no sabes si la solicitud llegó"; lo segundo es "la solicitud llegó, la tarea se ejecutó y falló".

Ejemplo mínimo de verificación

Usa un envío limpio para demostrar que tu clave y tu conectividad funcionan, y aislar el 502/503 como un problema temporal. Usa un id de modelo que sepas que funciona (por ejemplo, gpt-image-2/text-to-image) e incluye Idempotency-Key para que los reintentos sean seguros:

# A healthy submit returns 200 with a taskId. If this works but a specific
# call just 502/503'd, that 502/503 was transient — not your setup.
curl -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-job-0001" \
  -d '{"model":"gpt-image-2/text-to-image","input":{"prompt":"a red bicycle on a white background"}}'

# Then poll the task you just created (swap in the returned id):
curl -sS https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Si el propio envío devuelve 200 y un taskId, tu autenticación y tu ruta de red funcionan correctamente, y el 502/503 anterior era una condición temporal del servidor/transporte: reintenta la llamada fallida (reutilizar la misma Idempotency-Key devuelve la tarea original, no una tarea duplicada). Si el envío devuelve en cambio 401 o 400, eso es un problema del lado del cliente, no un 502/503.

Lecturas relacionadas

• Tiempo de espera de tareas de HiAPI y error 504: cómo solucionarlo — por qué un 504 en bruto no procede de HiAPI y qué significa TASK_TIMEOUT.
• Error TASK_FAILED de HiAPI: causas y cómo solucionarlo — cómo tratar las tareas que devuelven 200 + "status": "fail".
• Cuando los trabajos de hiapi /v1/tasks se cuelgan o agotan el tiempo: diagnóstico y reintentos — análisis detallado de los intervalos de sondeo y las estrategias de reintento.
• Cómo solucionar el error de límite de tasa (429) de HiAPI — cuando el verdadero problema es la tasa de envío y no la disponibilidad.
• ¿Por qué se siguen cobrando las solicitudes fallidas de HiAPI? — cómo funcionan las reservas y los reembolsos de las tareas fallidas.

Preguntas frecuentes

¿El 502 o el 503 son culpa mía? No. Ambos son respuestas 5xx y pertenecen al lado del servidor o al transporte. Tu clave de API y tu cuerpo de solicitud no son el desencadenante: los 4xx (400/401/402) son la categoría que tú provocas y que puedes corregir. La respuesta correcta a un 502/503 es reintentar de forma idempotente, no cambiar el código.

¿Cuál es la diferencia entre 502 y 503 en HiAPI? El 503 es el código de "plataforma temporalmente no disponible" documentado en HiAPI (error_code: TEMPORARILY_UNAVAILABLE) y proviene de la propia plataforma. El 502 no figura entre los códigos de estado documentados de HiAPI; en HTTP estándar lo emite un gateway o proxy de la cadena cuando el upstream devuelve una respuesta no válida. Ambos son temporales y ambos requieren reintentar con retroceso, pero el 502 también puede apuntar a un proxy de tu propia red.

¿En qué se diferencia el 503 del 504? El 503 indica que el servicio no está disponible temporalmente o está sobrecargado. El 504 Gateway Timeout indica que en algún punto se esperó demasiado tiempo una respuesta. La documentación de HiAPI no enumera el 504; si lo ves, significa que algún gateway o proxy de la cadena dejó de esperar. El propio estado de "tardó demasiado" de HiAPI es el resultado de tarea TASK_TIMEOUT (HTTP 200 + "status": "fail"). Consulta la guía sobre 504 más arriba.

¿Cómo distingo un 502/503 de un resultado TASK_FAILED? Mira el código de estado HTTP. Los 502/503 son errores HTTP sin payload de tarea. TASK_FAILED llega como HTTP 200 con "status": "fail" y un objeto error: la tarea se aceptó y se ejecutó. Usa reintentos con retroceso para los 502/503; para TASK_FAILED, reintenta una vez y luego lee error.message.

Si reintento tras un 502/503, ¿me cobran dos veces o se crean tareas duplicadas? Si envías la cabecera Idempotency-Key en POST /v1/tasks, no. Reutilizar la misma clave + el mismo cuerpo de solicitud devuelve el taskId original (Idempotent-Replay: true) sin crear una tarea duplicada. Además, las tareas fallidas nunca se cobran: en cuanto una tarea alcanza su estado terminal de fallo, el importe reservado en la creación se reembolsa íntegramente.

¿Cuánto tiempo debería aplicar retroceso y cuándo debería escalar? Usa retroceso exponencial con jitter (por ejemplo, 1 s, 2 s, 4 s, 8 s, con un límite y algo de aleatoriedad). Si el 502/503 sigue devolviéndose tras varios reintentos durante varios minutos, deja de reintentar agresivamente y contacta con soporte adjuntando el request_id del cuerpo del error: un 5xx persistente suele significar un incidente temporal de la plataforma, no algo que resuelva un bucle de reintentos más rápido.

¿Debo modificar el payload de la solicitud cuando veo un 502/503? No. Un 502/503 no es un error de validación, así que cambiar parámetros no ayuda y podría enmascarar la verdadera causa temporal. Mantén la solicitud igual, añade Idempotency-Key si aún no lo habías hecho y reintenta con retroceso.