· reAPI Team
Errores API 500: cuándo reintentar una solicitud de video
Gestiona errores API 500 sin duplicar tareas de video de pago. Comprueba si se aceptó el envío, recupera los ID de tarea, limita los reintentos y reanuda los flujos de trabajo de forma segura.

Un clic, un mensaje de error y luego otro clic. En una aplicación de video, eso puede bastar para crear dos generaciones de pago mientras la interfaz sigue mostrando un error.
Considera una solicitud hipotética: el servidor acepta el primer envío, inicia una tarea y pierde la respuesta mientras vuelve al cliente. El cliente recibe un error y vuelve a enviar la solicitud. Si el endpoint crea una tarea nueva por cada envío aceptado, ambos trabajos pueden continuar. El segundo clic no reparó la primera respuesta; pidió otro video.
Esta es la dificultad práctica de los errores API 500. Las directrices de AWS sobre reintentos advierten que una respuesta fallida o un tiempo de espera agotado no demuestra que la operación no haya tenido efectos secundarios.[1] Antes de volver a intentar una generación, averigua qué estaba haciendo la solicitud fallida y qué pruebas de su aceptación siguen disponibles.
Encuentra la solicitud que falló
Un mensaje como «Request failed with status code 500» identifica un resultado HTTP, no el estado del video. MDN define el código 500 como una condición inesperada del servidor que impidió completar la solicitud.[2] No te dice qué componente falló, no demuestra que todas las entradas fueran válidas ni promete que esperar vaya a solucionarlo.
Consulta el método y la URL en el registro del cliente. Un fallo en el POST de generación tiene consecuencias distintas de un fallo al obtener una tarea existente. La descarga de un archivo puede fallar después de que ambas operaciones hayan tenido éxito. Una interfaz que agrupa los tres casos bajo «falló la generación» pierde la distinción necesaria para recuperarse.
Guarda la hora UTC, el modelo, el estado, el cuerpo de la respuesta y cualquier identificador de solicitud o tarea disponible. Oculta las credenciales antes de compartir registros. Si la respuesta es HTML en vez del formato de error API documentado, conserva también ese dato; no deduzcas un fallo del modelo a partir de una página de error genérica.
En el primer clic hipotético, la cuestión es si tienes un ID de tarea. Busca la respuesta al envío guardada por tu servidor, la salida del flujo de trabajo pertinente y cualquier registro de callback documentado. Comprueba la cuenta o el proyecto que realmente envió la solicitud. Una cuenta distinta del panel no puede aclarar si este envío creó un trabajo.
Con un ID de tarea, continúa desde esa tarea
Si recuperaste el identificador, usa la operación de lectura documentada por el proveedor. En reAPI, GET /api/v1/tasks/{id} obtiene la tarea sin consumir créditos.[3] Es el lugar adecuado para reanudar la observación; volver a enviar el cuerpo original de generación crea un envío independiente.
Lee el estado de la tarea en la respuesta. reAPI devuelve HTTP 200 cuando encuentra una tarea, incluso cuando su estado es failed.[4] Por lo tanto, HTTP 200 no significa que el video haya tenido éxito. Del mismo modo, un 500 al consultar la tarea no demuestra que el video haya fallado. Significa que esa consulta no te dio una respuesta útil.
Gestiona una tarea completada mediante los campos de salida documentados. Guarda el archivo que necesitas en vez de dejar que la aplicación espere una segunda generación. Una tarea en proceso sigue bajo observación. Si la tarea falló, lee el error y la información de liquidación antes de decidir si tiene sentido intentarlo de nuevo.
La tarea fallida y su cargo están relacionados, pero son cosas distintas. reAPI documenta los reembolsos por fallos y casos específicos de algunos modelos en los que una comprobación de seguridad posterior a la generación puede bloquear un resultado después de que se haya producido una generación facturable.[3] Conserva el registro real de uso de la tarea. Un aviso genérico de «error del servidor» no demuestra que deban desaparecer todos los cargos; la facturación de las generaciones fallidas depende de la tarea en estado terminal y de la política aplicable.
Sin ID, deja sin resolver si se aceptó
El caso más difícil es el primer clic sin una respuesta de envío utilizable. Asigna a esa operación un estado explícito sin resolver en tu aplicación. Por ejemplo, un valor interno acceptance_unknown puede distinguirla del trabajo que nunca se envió y del trabajo cuyo fallo confirmó el proveedor. Este es un estado sugerido para la aplicación, no un campo que devuelvan todas las API.
Conserva un ID de operación local estable y asigna a una persona responsable de la recuperación. Puede conciliar las pruebas que la integración realmente ofrezca: respuestas guardadas, callbacks, historial de tareas autorizado o resultados de una consulta al soporte. Si más adelante identificas una tarea, vincúlala a la operación original y continúa desde ahí.
Una columna local de ID de tarea vacía solo demuestra que tu aplicación no guardó un ID. La respuesta podría haberse perdido después de la aceptación. Del mismo modo, tu ID de operación local no llega automáticamente al proveedor ni hace que su endpoint de creación deduplique solicitudes. Te ayuda a organizar las pruebas; no demuestra una ejecución exactamente una vez.
Ten el mismo cuidado con el encabezado Idempotency-Key. HTTP POST no es idempotente por naturaleza, y la seguridad de repetirlo depende del contrato real del endpoint.[5] reAPI indica explícitamente que registra este encabezado, pero no lo usa para deduplicar generaciones. Repetir un POST aceptado con la misma clave puede crear otra tarea y otro cargo.[6]
Si las pruebas siguen sin ser concluyentes, iniciar deliberadamente un reemplazo todavía puede ser una decisión de negocio. Regístralo como otro intento vinculado a la operación original sin resolver y contempla la posibilidad de que ambos se completen. No cambies silenciosamente el primer intento a «no creado» solo para simplificar la cola de reintentos. Borrarías precisamente el registro que necesitas si llega tarde un resultado o un cargo.
Comprueba qué repetirá n8n
La misma ambigüedad puede pasar inadvertida en un editor de flujos de trabajo. Un nodo llamado «Generate Video» puede enviar el trabajo y después esperar el resultado. Un nodo en rojo puede indicar que terminó el tiempo de espera mientras la predicción remota sigue ejecutándose.
La documentación oficial de la integración de n8n de WaveSpeed describe exactamente este comportamiento: el nodo de generación envía una predicción y espera el resultado. Un tiempo de espera positivo puede hacer fallar el nodo mientras la predicción continúa. La documentación advierte que Retry On Fail de n8n vuelve a ejecutar todo el nodo y produce una predicción nueva con un cargo independiente; los fallos transitorios de sondeo ya se reintentan internamente.[7] Esta advertencia se aplica a esta integración, no automáticamente a todos los nodos de la comunidad.
En un flujo de trabajo creado con nodos HTTP Request, inspecciona la acción del nodo configurado para reintentar. n8n documenta Retry on Fail como una opción de nivel de nodo.[8] Si ese nodo envía el POST de generación, otro intento vuelve a enviar ese POST. Si solo lee una tarea conocida, la acción repetida es la lectura. El texto de error visible del flujo no sustituye la inspección del nodo.
Un diseño útil consiste en guardar el ID de tarea aceptado entre el envío y el sondeo. Así, la recuperación puede reanudar el paso de lectura sin volver a pasar por la creación. Esto no resuelve el caso de pérdida de la respuesta de envío descrito antes; conserva esa ruta sin resolver por separado. También conviene inspeccionar la ejecución completa si la vuelves a ejecutar manualmente, porque podrían repetirse pasos de creación anteriores que ya habían tenido éxito.
Volvamos al doble clic hipotético: sustituir el segundo clic por un reintento automático del nodo no cambia el problema de facturación. La aplicación aún necesita saber si está consultando el trabajo original o solicitando uno nuevo.
Reintenta la lectura con un punto de parada
Un fallo temporal al leer una tarea conocida es un caso más sencillo para reintentar. Mantén la misma identidad de tarea, sigue las reglas documentadas de sondeo y límites de solicitudes del endpoint, y detén el bucle inmediato cuando se agoten los intentos permitidos o el presupuesto de tiempo transcurrido.
AWS describe la espera exponencial con límite, la aleatoriedad y los límites de intentos para evitar sobrecargar una dependencia que ya tiene problemas.[1] La aleatoriedad distribuye en el tiempo los siguientes intentos de los clientes, en vez de programarlos todos para el mismo instante. Estas técnicas gestionan la carga de reintentos; no convierten un POST de creación en una operación deduplicada.
Elige una capa que se encargue de esta recuperación. Si un SDK, un nodo del flujo y un worker externo repiten cada uno por su cuenta, el tráfico resultante puede superar lo que sugiere el ajuste externo. Revisa los reintentos que ya incluye la integración antes de añadir otro bucle.
Cuando termine el presupuesto de lectura, conserva el ID de tarea para conciliarlo más adelante. Un plazo límite del cliente indica cuánto esperó ese cliente. A menos que haya tenido éxito una operación de cancelación documentada, no demuestra que la generación remota se haya detenido. Muestra un estado de recuperación sin resolver en vez de ofrecer un botón de «volver a intentar» sin matices que envíe trabajo nuevo.
Comprueba el error específico antes de elegir un reemplazo
Cuando tengas un error estructurado, lee su código y el alcance documentado. Por ejemplo, reAPI identifica 60001 y 60002 como fallos al guardar una tarea o iniciar un flujo de trabajo, con devolución de créditos.[4] Esos casos documentados respaldan una decisión de recuperación distinta de la que corresponde a una respuesta HTML 500 desconocida o a una conexión perdida después del envío. No extiendas ese reembolso a todos los errores del servidor.
Si la respuesta específica identifica una entrada no válida o un medio inutilizable, corrige el problema indicado según la documentación de ese endpoint antes de enviar otro intento. Conserva las pruebas del intento original y trata el envío corregido como trabajo nuevo; cambiar una entrada no resuelve la incertidumbre sobre la aceptación anterior.
«El servidor no puede procesar esta solicitud en este momento» también es incompleto sin el estado HTTP y los detalles de la respuesta. Cambiar repetidamente el prompt, actualizar el navegador o aumentar el tiempo de espera no identifica dónde se produjo el fallo del servidor. Para un endpoint gestionado por un proveedor, facilita el método, la URL, la hora UTC y los identificadores disponibles mediante su proceso de soporte; la guía de errores de reAPI especifica estas pruebas.[4]
Otro proveedor puede ser un reemplazo útil si sus entradas, salidas y condiciones operativas admitidas encajan con la tarea. Pero un nombre de host distinto por sí solo no demuestra que la ruta de fallo sea independiente. Un reemplazo exitoso tampoco aclara qué ocurrió con el envío original. Mantén visibles ambos intentos, incluida cualquier tarea original que termine más tarde.
Antes de reanudar una cola pendiente, contabiliza el trabajo que ya se envió. Las tareas conocidas necesitan seguir observándose o tener un resultado registrado; los envíos desconocidos necesitan una persona responsable y una decisión explícita sobre el reemplazo. El primer reintento exitoso es útil, pero la recuperación solo se entiende cuando puedes explicar qué trabajos remotos podrían existir para cada solicitud de usuario.
Referencias
- AWS Builders Library: Timeouts, retries, and backoff with jitter. Guía de ingeniería publicada por primera vez en 2019; efectos secundarios, reintentos limitados y amplificación de reintentos.
- MDN: HTTP 500 Internal Server Error. Definición e investigación del lado del servidor.
- reAPI Tasks. Sondeo, estado, salida y semántica de liquidación.
- reAPI Errors. Códigos de fallo específicos y pruebas para soporte. Las decisiones de reintento aquí también aplican el contrato de envío de la referencia 6.
- MDN: Idempotent. Semántica de los métodos HTTP y límites de suponer que repetir una solicitud es seguro.
- Descripción general de la API de reAPI. Envío de generaciones y contrato de Idempotency-Key.
- Documentación oficial de la integración de n8n de WaveSpeed. Tiempo de espera del nodo, reintentos del nodo completo y predicciones con cargos independientes; consultada el 15 de noviembre de 2026.
- Documentación oficial de n8n sobre problemas habituales de HTTP Request. Retry on Fail y ajustes de reintento del nodo; consultada el 15 de noviembre de 2026.