Crea en n8n un flujo resiliente para extraer datos de incidentes de API
Diseña un flujo de n8n que extraiga datos de incidentes de una API, valide su estructura, haga visibles los errores de reintento y validación, y envíe las acciones de seguimiento de riesgo a aprobación humana.
Resumen · TL;DR
Usa un flujo de n8n por etapas para obtener datos de incidentes, validar los campos obligatorios antes del análisis y hacer visibles los errores, en vez de dejar pasar registros incompletos sin avisar. Limita los reintentos y reserva la aprobación humana para las acciones que puedan modificar datos o contactar a otras personas.
Puntos clave
- Separa la extracción de API, la validación, el diagnóstico y la corrección para que cada error tenga una señal clara.
- Valida explícitamente el contrato de respuesta: un estado HTTP satisfactorio no garantiza que los datos de incidentes sean utilizables.
- Reintenta los errores transitorios de solicitud con un límite, pero envía los reintentos agotados y los registros no válidos a rutas de revisión distintas.
- Usa la aprobación humana para llamadas a herramientas con consecuencias; no la uses como sustituto de validar los datos extraídos.
En esta página (8)
Decisión de diseño: diagnosticar automáticamente y actuar con cautela
Un flujo de incidentes de API no debería considerar que «la solicitud se completó correctamente» equivale a «los datos son seguros para usar». Un servicio puede devolver HTTP 200 aunque falte un campo, la lista de incidentes esté vacía o la estructura de la respuesta haya cambiado después de una implementación. En n8n, separa la extracción de la validación y luego expón cada error mediante una ruta identificada.
Una secuencia práctica sería: activador Schedule o Webhook → HTTP Request → normalizar la respuesta → validar los campos obligatorios → crear un resumen de diagnóstico → notificar o enviar a revisión. Si las consecuencias lo justifican, somete a una decisión humana cualquier acción que modifique un registro, abra un ticket o envíe un mensaje externo.
Los ejemplos siguientes son ilustrativos: las etiquetas de los nodos, las estructuras de respuesta y los ajustes dependen de la versión de n8n y de la API. No constituyen una exportación de un flujo probado.
Requisitos previos y contrato de respuesta
Antes de crear los nodos, identifica el endpoint de incidentes, el método de autenticación, los límites de solicitudes y los campos que realmente necesita el diagnóstico. Por ejemplo, supongamos que la API debe devolver un objeto con un arreglo incidents, donde cada incidente tiene un ID, un estado y una marca de tiempo. Confirma esta estructura con la documentación de la API o con una respuesta real; no la deduzcas a partir de una solicitud satisfactoria.
Usa credenciales guardadas en el sistema de credenciales de n8n en lugar de incluir secretos directamente en un nodo Code. Define qué se considera un resultado útil: un arreglo vacío puede ser válido cuando no hay incidentes, mientras que la ausencia del arreglo podría indicar un cambio incompatible en la respuesta.
Configura la extracción y los reintentos limitados
- Añade un Schedule Trigger para realizar comprobaciones periódicas o un Webhook si un sistema ascendente inicia el diagnóstico.
- Añade un nodo HTTP Request con el endpoint de incidentes, los parámetros de consulta necesarios y la autenticación configurada.
- Configura un tiempo de espera finito y, si está disponible en tu versión, el comportamiento del nodo para reintentar ante errores. Establece un límite bajo de reintentos y un intervalo adecuado a los límites de solicitudes de la API. Evita los reintentos ilimitados: pueden prolongar una ejecución fallida y añadir carga durante una interrupción del servicio.
- Conserva suficiente información de la respuesta para inspeccionar el estado HTTP y el cuerpo. Revisa las opciones de respuesta del nodo para tu versión de n8n; los ajustes exactos pueden variar.
- Envía los errores de solicitud que persistan tras los reintentos a una ruta de error explícita. Según el diseño de tu flujo, utiliza la salida de error del nodo o un flujo de error específico. Incluye en la alerta el ID de ejecución, la etiqueta del endpoint, el contexto de los intentos si está disponible y el mensaje de error. Nunca registres encabezados de autorización ni tokens.
Los reintentos son apropiados ante problemas temporales, como un tiempo de espera agotado o una respuesta del servidor que admita reintentos. No solucionan credenciales no válidas, solicitudes mal formadas ni discrepancias de esquema. Si la API documenta Retry-After, respeta ese valor en lugar de reintentar inmediatamente.
Valida antes del diagnóstico
Coloca un nodo Code después de recibir una respuesta satisfactoria y comprueba los campos de los que depende el siguiente paso. Este ejemplo supone que el nodo anterior proporciona el cuerpo de la respuesta como body; adapta la ruta de la propiedad a la configuración de tu HTTP Request.
const body = $json.body;
const valid =
body !== null &&
typeof body === 'object' &&
Array.isArray(body.incidents) &&
body.incidents.every((incident) =>
incident &&
typeof incident.id === 'string' &&
typeof incident.status === 'string' &&
typeof incident.timestamp === 'string'
);
if (!valid) {
return [{
json: {
validationFailed: true,
reason: 'Expected incidents array with id, status, and timestamp',
receivedType: Array.isArray(body) ? 'array' : typeof body,
executionId: $execution.id
}
}];
}
return body.incidents.map((incident) => ({
json: {
validationFailed: false,
incidentId: incident.id,
status: incident.status,
timestamp: incident.timestamp
}
}));
Esto es una comprobación sencilla del contrato, no un validador completo de JSON Schema. Añade las comprobaciones de dominio que sean necesarias; por ejemplo, valida el formato de la marca de tiempo o limita el estado a los valores documentados por la API. No reemplaces silenciosamente los campos ausentes por valores predeterminados inventados. Usa un nodo IF para enviar los elementos validationFailed a una alerta por cambio de esquema o a una cola de revisión, y los registros válidos al diagnóstico.
Haz visibles los errores
Diseña señales diferenciadas para cada problema:
| Señal | Qué significa | Respuesta útil |
|---|---|---|
| Error de solicitud tras los reintentos | No se pudo obtener información de la API | Enviar una alerta con el ID de ejecución y detalles del error sin datos sensibles |
| Error de validación | Se recibió una respuesta, pero no cumple el contrato esperado | Conservar una muestra anonimizada y revisar el cambio de estructura |
| Respuesta válida sin incidentes | La extracción funcionó y no encontró registros | Registrar un resultado vacío satisfactorio; evitar avisos urgentes salvo que la política lo exija |
| Diagnóstico incierto | Los datos son válidos, pero no permiten llegar a una explicación con suficiente confianza | Solicitar una revisión humana en vez de afirmar una causa |
Elige umbrales de alerta adecuados para el intervalo de consulta. Si cada intento de reintento envía una alerta aparte, una sola interrupción puede generar demasiado ruido; envía una alerta cuando falle la ejecución final o agrupa los errores.
Añade revisión humana a las acciones con consecuencias
Cuando sea posible, mantén el diagnóstico en modo de solo lectura: extrae incidentes, resume los campos pertinentes y envía un informe. Si utilizas un AI Agent para llamar a herramientas, limita sus entradas a datos validados y exige aprobación para acciones como modificar un incidente, eliminar un registro o enviar un mensaje externo.
La documentación de n8n describe la revisión humana para herramientas seleccionadas conectadas a un AI Agent: el flujo se pausa hasta que se aprueba o rechaza la acción y, si se aprueba, la herramienta se ejecuta con los parámetros propuestos. La documentación menciona canales de aprobación como Slack, Telegram y n8n Chat, entre otros. Muestra a quienes revisan la solicitud el nombre de la herramienta y sus parámetros, además de los ID de los incidentes y una explicación breve de la acción propuesta. Indica al agente qué hacer si se rechaza la aprobación; el rechazo no debe interpretarse como permiso para probar otra herramienta que pueda tener consecuencias. Consulta la documentación de n8n sobre intervención humana.
Esta función documentada se refiere a las llamadas a herramientas de AI Agent. En un flujo sin agente, diseña una tarea o un paso de aprobación adecuado para tu configuración, en lugar de asumir que la función de revisión de AI Agent bloquea automáticamente todos los nodos.
Lista de comprobación para solucionar problemas
- El validador rechaza todas las respuestas: inspecciona la salida real de HTTP Request y actualiza la ruta del cuerpo que habías supuesto; las API suelen devolver los resultados dentro de estructuras envolventes distintas.
- Los reintentos no ayudan: comprueba las credenciales, los parámetros de la solicitud, los límites de solicitudes y si el error es transitorio. Corrige los errores permanentes de la solicitud en lugar de aumentar el número de reintentos.
- El flujo se ejecuta correctamente aunque falten campos de incidentes: asegúrate de que la validación se ejecute antes de cualquier nodo de resumen o acción, y prueba tanto los valores ausentes como los de tipo incorrecto.
- Quienes revisan la solicitud no pueden evaluar la acción propuesta: incluye el incidente de origen, los parámetros propuestos y una explicación clara de las consecuencias de aprobarla; omite secretos y datos personales innecesarios.
- Una nueva respuesta de la API rompe el diagnóstico: dirige los errores de esquema a una señal distinta y actualiza el contrato solo después de confirmar el cambio previsto en la API.
Conclusión
Un extractor de incidentes robusto en n8n deja claramente diferenciados tres resultados: error de solicitud, datos no válidos y datos válidos listos para el diagnóstico. Usa reintentos limitados para problemas transitorios de obtención, comprobaciones explícitas del contrato antes del análisis y aprobación humana para las acciones de herramientas con consecuencias. Esta separación facilita la investigación de errores y evita que una respuesta incompleta conduzca a una decisión insegura.
FAQ
¿Una respuesta HTTP 200 significa que los datos de incidentes son válidos?
No. Significa que la solicitud devolvió un estado satisfactorio, pero el cuerpo aún puede estar vacío, mal formado o no incluir algunos campos. Valida el contrato de respuesta antes de usar los datos para el diagnóstico.
¿Debería reintentar los errores de validación de esquema?
Por lo general, no. Una discrepancia de esquema suele requerir una investigación o una actualización intencional del contrato, no otra solicitud idéntica. Envíala a una ruta distinta de revisión o alerta.
¿Puede n8n exigir aprobación antes de ejecutar cada nodo del flujo?
La documentación de n8n citada describe la revisión humana para herramientas seleccionadas conectadas a un AI Agent. No indica que esta función controle nodos arbitrarios de un flujo estándar.
¿Qué debe incluir una alerta de error de incidentes?
Incluye un identificador de ejecución del flujo, un error o motivo de validación sin datos sensibles y suficiente contexto del endpoint para investigar. Evita incluir credenciales, encabezados de autorización y datos sensibles innecesarios de la respuesta.
Artículos relacionados
Guides
Crea en n8n un flujo de preguntas y respuestas sobre documentos con citas validadas y revisión humana
Diseña un flujo de trabajo en n8n que extraiga evidencia documental, valide respuestas estructuradas, reintente de forma segura y derive los resultados inciertos a revisión humana.
Guides
Crea un flujo de extracción de datos recuperable en n8n
Diseña un flujo de extracción en n8n que valide registros, reintente fallos transitorios y derive las excepciones a revisión humana sin duplicar escrituras.
Guides
Crea un flujo de extracción de datos en n8n que proteja la privacidad
Diseña un flujo de extracción en n8n que valide los resultados estructurados, gestione los fallos de forma segura y envíe las acciones sensibles a revisión humana.
Guides
Crea un flujo de clasificación de tickets de soporte en n8n con validación, reintentos y aprobación humana
Diseña un flujo de trabajo en n8n que extraiga campos de los tickets de soporte, los valide, gestione los fallos y exija aprobación humana antes de ejecutar acciones importantes.