Depura tus workflows de n8n antes de culpar a la integración
Un método práctico de cuatro capas para saber si un fallo en n8n viene de las credenciales, los datos y mapeos, la API externa o la lógica de tu workflow.
Comprobado con las fuentes citadas el .
Un modelo de depuración en cuatro capas
Cuando un workflow que ayer funcionaba muestra hoy un nodo rojo con error, lo peor que puedes hacer es ponerte a editar sin más. Si adivinas y cambias varias cosas a la vez, enseguida pierdes la pista de qué versión provocó cada error. Un hábito mejor es el aislamiento controlado: deja fija una entrada que falla, cambia una capa cada vez y apunta si el mismo fallo sigue ahí.
Esta guía clasifica los fallos en cuatro capas. Es un modelo editorial para organizar tus comprobaciones y no dice nada sobre la frecuencia con la que cada capa es la causa. Las credenciales deciden si tienes permiso para hablar con el servicio. La entrada y los mapeos deciden si envías los valores que querías enviar. La API externa decide si el otro lado acepta tu petición. La lógica del workflow decide qué hacen tus propios nodos con los datos antes y después de la llamada. Desde fuera, las capas pueden parecerse, pero cada una deja pruebas distintas. Por eso importa el orden en que las revisas.
Los pasos siguientes son un método de trabajo, no un resultado medido. La documentación de n8n describe las herramientas, pero no publica estudios que demuestren que este orden resuelve los problemas más rápido. Usa cada paso para reunir pruebas, no como demostración de una causa.
Empieza por la ejecución fallida y conserva su entrada
Antes de tocar ningún nodo, abre la lista de ejecuciones y localiza el fallo exacto que estás investigando. Puedes filtrar la lista para acotarla, así trabajas sobre un fallo real y no sobre la vaga sensación de que el workflow no para de romperse.
Esa ejecución es tu prueba. Abre el nodo que falla y lee su panel INPUT, que muestra exactamente los items que recibió el nodo. Guarda esos datos en un lugar seguro, porque todos los pasos posteriores se comparan con esta entrada. Si vuelves a lanzar el workflow con datos nuevos, cambias dos cosas a la vez y pierdes la comparación.
Conviene conocer pronto dos límites. Si eliminas un workflow, su historial de ejecuciones desaparece con él, así que no limpies un workflow roto antes de terminar el diagnóstico. Además, los datos de ejecución personalizados tienen restricciones según el plan y el registro, de modo que lo que puedas añadir a las ejecuciones depende de tu configuración.
Comprueba las credenciales por separado
Las credenciales son una comprobación temprana razonable, porque n8n ya las prueba. Cuando guardas una credencial, n8n la prueba para confirmar que funciona. Si una credencial guardada no supera esa prueba, trátala como lo primero que hay que arreglar antes de investigar otras capas.
Pero no saques demasiadas conclusiones de un resultado positivo. Que la prueba salga bien no demuestra que la credencial tenga permiso para todos los endpoints y operaciones que usa tu workflow. Una prueba superada acota la búsqueda, pero no la termina.
Aquí es donde falla la costumbre de culpar a las credenciales de cualquier error de API. Considera las credenciales como la capa que falla solo cuando la prueba de la credencial falla, o cuando una petición reproducida muestra un problema de autenticación o autorización. Si no, pasa a la siguiente capa.
Sources: S7
Revisa la forma de la entrada y los mapeos de campos
A continuación, compara lo que el nodo está configurado para enviar con lo que realmente recibió. Pon los parámetros del nodo junto a los datos INPUT guardados y revisa cada expresión mapeada. ¿Existe el campo? ¿Está en la ruta que esperabas? ¿Es el valor que necesita el siguiente paso?
Ayuda saber qué hace el mapeo en n8n. Mapear significa referenciar datos de nodos anteriores. Apunta a los datos, pero no los modifica. Así que, si el valor o la ruta ya son incorrectos antes de que se ejecute la petición, tienes un problema de entrada o de mapeo, y no hace falta mirar la API todavía.
La documentación trata los errores de vinculación de items en una página aparte y no enumera mensajes de error concretos de mapeo. No esperes una tabla de causas. Lo fiable es comprobar a mano las expresiones contra la entrada guardada.
Sources: S2
Reproduce la petición a la API fuera del workflow
Si las credenciales pasan la prueba y los valores salientes parecen correctos, saca la petición de n8n. Construye la misma llamada con curl y ejecútala con la opción detallada (--verbose, o -v para abreviar). El modo detallado muestra lo que curl envía al servidor, además de información de diagnóstico adicional.
Esto solo te dice algo si la copia es exacta. El método, la URL, la autenticación, las cabeceras, los parámetros de consulta y el cuerpo tienen que coincidir con la petición del workflow. Una llamada con curl a la que le falta una cabecera es otra prueba distinta, no una comparación justa.
Dentro de n8n, activa en el nodo HTTP Request la opción que devuelve la respuesta completa: el código de estado y las cabeceras, además del cuerpo. Como consejo general, asegúrate de ver el estado, las cabeceras y el cuerpo de las respuestas fallidas antes de cambiar nada. Lo que significan para un servicio concreto sigue viniendo de la documentación de esa API, que cubre sus errores, límites de uso, esquemas y reglas de autenticación.
Trata el resultado como una pista, no como una prueba. Si la petición equivalente también falla, revisa el formato de la petición o el servicio externo. Si funciona, vuelve a tu configuración y tu lógica en n8n.
Prueba la lógica del workflow con datos de ejecución guardados
La última capa es tu propia lógica: ramas, código, merges y el orden en que los datos recorren el workflow. n8n te permite trabajar desde el propio fallo. Puedes abrir una ejecución fallida, cambiar el workflow para corregirlo y volver a ejecutarlo con los datos de la ejecución anterior. La entrada se mantiene igual mientras cambias una sola cosa.
Si la misma entrada da ahora un resultado distinto, tu cambio es una explicación probable. Pero un reintento correcto también puede deberse a un cambio en el otro servicio, al fin de una caída temporal o a credenciales distintas. Considera una ejecución correcta como buena señal, no como respuesta definitiva.
Dónde puedes usar esto depende de cómo ejecutes n8n. Funciona en todos los planes de n8n Cloud. En n8n autoalojado, solo está disponible en las ediciones registradas Community, Business y Enterprise.
Sources: S3
Añade gestión de errores antes de producción
Depurar es más fácil cuando los fallos avisan de que han ocurrido. La documentación de n8n indica crear un workflow nuevo con el Error Trigger como primer nodo, lo que te da un lugar dedicado para gestionar los fallos.
Ten claro lo que hace. Un workflow de errores informa de los fallos, pero no los evita. Algunos detalles del error dependen de si se guardan las ejecuciones, de si hubo reintentos y de si falló el propio nodo disparador.
Un workflow de errores sirve para hacer visibles los fallos, de modo que tengas un motivo para abrir la ejecución fallida, que es justo donde empezó esta guía.
Sources: S4
Una checklist de depuración reutilizable
Aquí tienes una rutina sugerida, no un procedimiento probado. Localiza la ejecución fallida exacta y guarda su entrada. Confirma que la credencial supera su prueba, teniendo en cuenta que eso no demuestra que tenga todos los permisos que necesitas. Compara cada expresión mapeada con la entrada guardada. Activa los detalles completos de la respuesta y anota el estado, las cabeceras y el cuerpo. Reproduce la petición exacta con curl en modo detallado. Vuelve a ejecutar los datos de ejecución guardados tras cada cambio individual. Después, añade un workflow con Error Trigger para enterarte enseguida del siguiente fallo.
En cada paso, escribe una línea sobre qué cambiaste y si el fallo se mantuvo. Esa nota te ayuda a decir qué capa probablemente falló, y no solo cuál editaste la última.
Sources: S1, S2, S3, S4, S5, S7, S8
