Introducción

Incluso el workflow mejor diseñado acabará encontrando una llamada a API que falla, un payload malformado o un timeout. En producción, esos fallos deben capturarse, registrarse y gestionarse de forma elegante — no silenciarlos ni dejar que tiren toda la ejecución. Esta lección cubre los tres pilares de los workflows confiables en n8n: manejo estructurado de errores, depuración con logs de ejecución y una checklist de pre-despliegue que puedes aplicar a cualquier integración.

Ramas de error en n8n

n8n ofrece dos mecanismos principales para capturar errores: el nodo Error Trigger y las salidas de error por nodo.

El nodo Error Trigger es un catch a nivel de workflow. Creas un workflow aparte cuyo único trigger es el nodo Error Trigger y luego apuntas tu workflow principal hacia él mediante Settings > Error Workflow. Cuando cualquier nodo del workflow principal lanza un error no capturado, n8n arranca automáticamente el workflow de error y le pasa un payload que incluye el nombre del workflow, el nodo que falló, el mensaje de error y el ID completo de la ejecución.

{
  "execution": {
    "id": "1042",
    "url": "https://your-n8n-instance/execution/1042",
    "retryOf": null,
    "error": {
      "message": "Request failed with status code 429",
      "stack": "..."
    },
    "lastNodeExecuted": "HTTP Request",
    "mode": "webhook"
  },
  "workflow": {
    "id": "7",
    "name": "Sync CRM Contacts"
  }
}

Dentro del workflow de error puedes enrutar ese payload a Slack, PagerDuty, un nodo de email o una fila de base de datos — lo que tu equipo monitorice.

Para un control más fino, los nodos individuales exponen un pin de salida secundario cuando activas "Continue on Fail" o habilitas la rama de error del nodo (disponible en HTTP Request, Code y la mayoría de nodos de integración). Conecta ese pin a un nodo posterior para gestionar el fallo en línea sin detener todo el workflow. Este es el patrón correcto cuando un único elemento fallido en un batch debe registrarse y saltarse, en lugar de abortarlo todo.

Uso de los logs de ejecución para rastrear fallos

Cada ejecución de n8n — exitosa o fallida — se almacena en el panel Executions. Abre cualquier ejecución y puedes inspeccionar los datos exactos de entrada y salida de cada nodo, lo que hace que rastrear un fallo sea directo.

El bucle práctico de depuración es este: ejecuta el workflow, abre la ejecución fallida, haz clic en el nodo rojo, lee la pestaña Output. Ahí están visibles tanto el mensaje de error como los datos de entrada que lo provocaron. En llamadas HTTP también verás el estado de la respuesta en crudo y el body, que suele ser más informativo que la cadena genérica de error.

Cuando el panel integrado no basta — por ejemplo, cuando necesitas inspeccionar transformaciones intermedias — inserta un nodo Code temporal que solo haga log de su entrada:

console.log(JSON.stringify($input.all(), null, 2));
return $input.all();

n8n muestra la salida de console.log dentro del detalle de ejecución del nodo, así que puedes leer la forma exacta de los datos en ese punto de la cadena. Elimina el nodo antes de desplegar.

Para workflows disparados por webhooks, usa el botón "Listen for Test Event" para capturar un payload entrante real y reproducirlo repetidamente durante el desarrollo. Esto evita tener que volver a disparar el sistema externo cada vez que iteras.

Aplicación de reintentos y timeouts

Las APIs externas fallan de forma transitoria. En lugar de construir lógica manual de reintentos en un nodo Code, configúralo a nivel de nodo. En cualquier nodo HTTP Request, abre los ajustes del nodo y define Max Retries (normalmente 2–3) y Retry Interval. n8n hará back off y reintento automáticamente en respuestas 5xx y errores de red.

Define siempre un Timeout explícito. Por defecto no hay timeout, lo que significa que un servicio upstream colgado bloqueará el hilo de ejecución indefinidamente. Un valor entre 10 000 y 30 000 milisegundos cubre la mayoría de las APIs REST.

{
  "options": {
    "timeout": 15000,
    "retry": {
      "maxTries": 3,
      "waitBetweenTries": 2000
    }
  }
}

Este JSON representa el objeto de opciones que configuras en la UI del nodo HTTP Request — no es algo que escribas a mano, pero resulta útil para entender la estructura subyacente cuando exportas y versionas tus workflows como archivos JSON.

Checklist de pre-despliegue

Antes de activar cualquier workflow en producción, repasa estos puntos.

Primero, sustituye todas las credenciales y URLs hardcodeadas por Credentials de n8n o variables de entorno accedidas mediante el objeto `$env`. Los secretos nunca deben aparecer como strings en plano dentro de los parámetros de los nodos.

Segundo, confirma que cada llamada externa tenga un timeout y, cuando proceda, configuración de reintentos.

Tercero, conecta un Error Workflow al workflow de producción desde Settings. Pruébalo añadiendo temporalmente un nodo Code que lance un error a propósito:

throw new Error('Test error — remove before deploy');

Verifica que tu canal de Slack o sistema de alertas recibe la notificación y luego elimina el nodo de prueba.

Cuarto, revisa el modo de ejecución. Los workflows disparados por schedule o por webhook deben tener "Save Execution Progress" activado para no perder el progreso parcial en caso de crash.

Quinto, limita lo que almacenas. Si el workflow procesa datos personales, configura "Save Data Error Execution" y "Save Data Success Execution" en "Latest only" o desactívalas, según tu política de retención de datos.

Resumen

Los workflows de n8n de calidad de producción combinan tres hábitos: enrutar los fallos de forma explícita usando Error Trigger o ramas de error inline en lugar de dejarlos desaparecer, usar el panel Executions y console.log para inspeccionar datos en cualquier punto de la cadena, y seguir una checklist de pre-despliegue consistente que cubra credenciales, timeouts, alertas y retención de datos. Estas prácticas no añaden mucho tiempo al principio pero eliminan la mayor parte de la depuración que de otro modo harías a las 2 de la mañana.