Monitoreo y solución de problemas de Flows

Dónde vigilar las ejecuciones, cómo leer una ejecución fallida hasta el nodo que se rompió y los cinco fallos que realmente encontrará: síntoma, causa y la solución que puede hacer usted mismo.

Qué vigilar#

• Monitor de ejecuciones (Integration → Runs): todas las ejecuciones en una lista: flow y versión, cómo se disparó (horario / evento / manual), estado (running, success, failed, retrying), duración y elementos procesados. Filtre por estado para ver solo los fallos.
• Detalle de la ejecución: haga clic en una ejecución para verla nodo a nodo: instantánea de entrada y salida de cada paso y, en el paso fallido, el mensaje de error exacto. Empiece siempre aquí.
• Logs y mensajes muertos (Integration → Logs): los elementos que fallan definitivamente quedan en la cola de dead letters con el flow, el nodo y el error. Tras corregir la causa, repita (replay) el elemento para procesarlo de nuevo, o descártelo si ya no hace falta.
• Salud de la conexión: una ejecución que falla en su primer nodo con error de autenticación es un problema de la conexión, no del flow; el botón Probar de la conexión lo reproduce en segundos.

Los cinco fallos siguientes cubren casi todo lo que verá. Para cada uno: cómo se ve, por qué ocurre y la solución, todo desde la interfaz.

1. Credenciales caducadas o inválidas#

• Síntoma: las ejecuciones fallan en el primer nodo con 401 / error de autenticación; la prueba de la conexión falla igual. Suele empezar de golpe tras semanas funcionando.
• Causa: la otra plataforma caducó o rotó la credencial: los tokens tienen vida útil (p. ej. Wish, 30 días; algunos tokens OAuth de usuario, horas) y los secretos cambian cuando alguien los regenera.
• Solución: (1) obtenga una credencial nueva en la plataforma (el directorio indica dónde); (2) abra la conexión, pegue el valor nuevo y guarde; (3) pruebe la conexión hasta que pase; (4) repita los dead letters que dejó la caída.

2. Mapping ausente o de tipo incorrecto#

• Síntoma: las ejecuciones fallan en un nodo intermedio con errores como «el campo X es obligatorio», «SKU sin mapear» o un valor rechazado por tipo incorrecto (texto donde va un número, fecha en formato equivocado). Los pedidos nuevos con SKUs nuevos son el disparador clásico.
• Causa: un campo de origen que el mapping espera venía vacío o ausente en ese documento, los dos sistemas no coinciden en el tipo de un campo, o un SKU del canal nunca se vinculó a un producto OMS.
• Solución: (1) abra la ejecución fallida y vea qué nodo y campo fallaron; (2) SKUs sin mapear: vincúlelos en la lista pendiente de Product Mapping; (3) campo ausente o de tipo erróneo: abra el mapping del flow (o de la conexión), mapee el campo correcto o añada un valor por defecto / conversión; (4) haga dry run, publique si editó el flow y repita el dead letter.

3. La otra plataforma limita la velocidad#

• Síntoma: las ejecuciones muestran «retrying» o fallan con 429 / «too many requests». Las ráfagas lo empeoran: tras una extracción manual grande o en punto, cuando muchos flows se disparan a la vez.
• Causa: cada plataforma limita las llamadas API por minuto/hora de una cuenta. El conector ya reintenta con espera (eso es «retrying»), pero una ráfaga sostenida puede agotar el cupo.
• Solución: (1) ante un «retrying» ocasional no haga nada: suele resolverse solo; (2) si se repite, baje la frecuencia de extracción en la conexión / el horario del flow; (3) escalone los horarios para que varios flows no golpeen la misma plataforma en el mismo minuto; (4) evite extracciones manuales repetidas mientras hay una cola reintentando.

4. Fallos de webhook / devolución#

• Síntoma: los datos que deberían llegar por push nunca llegan (tracking o confirmaciones de fulfillment ausentes, avisos de pedidos nuevos detenidos) mientras la extracción manual sigue funcionando. Los logs muestran errores de entrega de webhooks.
• Causa: la plataforma emisora no pudo entregar a Docklify (problema temporal de red), la suscripción se perdió al cambiar las credenciales, o la conexión se desactivó y reactivó sin volver a registrar el callback.
• Solución: (1) revise en Integration → Logs los errores de webhook y sus horas; una ráfaga corta que ya paró no requiere acción; (2) pruebe la conexión: una prueba exitosa revalida el registro del callback en la mayoría de las plataformas; (3) si los pushes siguen sin llegar, desactive y reactive la conexión para forzar una suscripción nueva; (4) haga una extracción manual para recuperar lo perdido y vigile el siguiente evento real.

5. Problemas de formato de datos#

• Síntoma: documentos sueltos fallan mientras otros de la misma conexión pasan: un pedido rechazado por dirección inválida, un teléfono con formato incorrecto, un código postal que no se puede interpretar o un peso con la unidad dentro del número.
• Causa: el dato en sí, tal como existe en la plataforma o el documento de origen, no cumple las reglas de formato del receptor. El flow y las credenciales están bien; el documento no.
• Solución: (1) abra la ejecución fallida y lea qué documento y qué campo se rechazó: el error lo nombra; (2) corrija el dato en el origen donde pueda (la dirección / el teléfono en el pedido o en la plataforma); (3) si la misma peculiaridad se repite desde esa plataforma, trátela una vez en el mapping: valor por defecto, recorte o conversión para ese campo; (4) repita el dead letter del documento corregido.