Crea un flujo de incidentes de API en n8n con validación, aprobación y señales de fallo útiles

El patrón seguro: diagnosticar primero y corregir solo con aprobación

Un flujo de incidentes de API no debería convertir cada solicitud fallida en una corrección automática. Un 503, una respuesta de éxito con un formato incorrecto y un tiempo de espera agotado son observaciones diferentes; no demuestran la misma causa raíz. En n8n, crea etapas separadas para capturar evidencias, comprobarlas, resumir las causas probables y aprobar cualquier acción con consecuencias.

El ejemplo siguiente es ilustrativo, no una exportación de flujo probada. Las etiquetas de los nodos y los campos de respuesta pueden variar según tu API y tu versión de n8n. El principio central del diseño es hacer visible la señal del fallo antes de pedirle a un AI Agent que la interprete.

Requisitos previos y esquema del flujo

Necesitas un flujo de n8n que pueda recibir o programar una comprobación de API, credenciales para la API supervisada y un canal donde enviar las notificaciones de incidentes. Si tienes previsto usar un AI Agent, configura su modelo y proporciónale únicamente las evidencias que necesita. Las herramientas de corrección solo deberían estar disponibles cuando exista una necesidad clara y deberían requerir revisión humana.

Un esquema útil es el siguiente:

1. Disparador: ejecuta una comprobación programada o recibe un evento de incidente.
2. HTTP Request: llama a un endpoint de estado o a la operación de API pertinente.
3. Validación: comprueba el estado y los campos de respuesta esperados; distingue los tiempos de espera agotados y los errores de solicitud de una respuesta ordinaria.
4. Normalización de evidencias: crea un único objeto de incidente con una marca de tiempo, la etiqueta del endpoint, el estado, la latencia si está disponible y un detalle breve del error.
5. Diagnóstico: pide a un AI Agent que resuma las causas plausibles y las lagunas de evidencia. Conecta herramientas de solo lectura si es necesario.
6. Notificación o aprobación: envía un informe de incidente conciso. Exige revisión humana antes de permitir que una herramienta cambie el estado.
7. Registro del resultado: captura si la acción fue aprobada, denegada o falló, y notifica al canal correspondiente.

Haz explícitas las señales de fallo de la API

No dependas de un único indicador de “fallo”. Comprueba al menos estos casos:

• Fallo de transporte: la solicitud agota el tiempo de espera, no puede conectarse o falla antes de que llegue una respuesta utilizable.
• Fallo HTTP: la API devuelve un estado que no indica éxito. Registra el código de estado y, cuando corresponda, un cuerpo de error truncado de forma segura.
• Fallo de contrato: la respuesta llega, pero faltan campos obligatorios o tienen tipos inesperados.
• Fallo de negocio: la solicitud HTTP tiene éxito, pero la respuesta informa de un error a nivel de aplicación.

Para un contrato de respuesta ilustrativo y sencillo, supón que el endpoint debe devolver un objeto JSON con status igual a ok y un campo service. Un paso de validación puede usar una lógica equivalente a:

const body = $json;
const valid = body.status === 'ok' && typeof body.service === 'string';

return [{
  json: {
    valid,
    signal: valid ? 'healthy' : 'contract_failure',
    service: typeof body.service === 'string' ? body.service : null,
    observedAt: new Date().toISOString(),
  },
}];

Este ejemplo presupone que el nodo HTTP ya ha producido un cuerpo de respuesta analizado. Adáptalo a la salida real del nodo y al contrato de tu API. Configura la gestión de errores de solicitud para que los fallos puedan llegar a una rama que registre el error en lugar de desaparecer de la ruta del incidente. Mantén las credenciales, las cabeceras de autorización y los datos sensibles de la respuesta fuera de las notificaciones y de las instrucciones del AI Agent.

Un registro de incidente debería responder a estas preguntas: ¿qué se comprobó, qué se esperaba, qué se observó y qué no pudo observarse? Evita convertir una señal desconocida en un diagnóstico categórico.

Proporciona evidencias a la IA, no autoridad

Pasa un objeto de incidente compacto al AI Agent, por ejemplo:

{
  "endpoint": "orders-health",
  "observedAt": "2025-01-15T12:00:00Z",
  "signal": "http_failure",
  "statusCode": 503,
  "expected": "HTTP success and status=ok",
  "observed": "HTTP 503; response body omitted"
}

Los valores son ilustrativos. En producción, usa la marca de tiempo y las evidencias de respuesta reales; no incluyas secretos ni datos de clientes sin una necesidad justificada. Pide al Agent que distinga los hechos observados de las hipótesis, indique qué evidencias faltan y recomiende la siguiente comprobación de solo lectura. Una instrucción útil es: “No afirmes una causa raíz a menos que la evidencia proporcionada la respalde. Si la evidencia es insuficiente, indica qué observación adicional ayudaría”.

Las herramientas de solo lectura podrían recuperar el registro de una implementación reciente o consultar un sistema de monitorización, si has conectado y configurado esas herramientas. No des por hecho que existe una integración o un esquema de parámetros concretos: verifica las entradas documentadas de la herramienta y pruébala con datos que no sean de producción.

Coloca la aprobación humana antes de los cambios

Para acciones como reiniciar un servicio, cambiar un registro o enviar un mensaje externo, utiliza una herramienta de AI Agent de n8n con un paso de revisión humana. n8n documenta que un flujo puede pausarse para solicitar aprobación; una herramienta aprobada se ejecuta con la entrada especificada por la IA, mientras que una llamada denegada se cancela. La aprobación puede canalizarse a través de medios compatibles, como Slack o la interfaz de n8n Chat, según tu configuración. Consulta la guía de n8n sobre herramientas con intervención humana.

Proporciona al revisor suficiente contexto para decidir: identificador del incidente, señales observadas, acción propuesta, servicio afectado y parámetros exactos de la herramienta. La documentación describe $tool.name y $tool.parameters para construir el contexto de revisión. Indica al Agent en su mensaje de sistema qué herramientas requieren aprobación, qué significa una denegación y cómo debe responder si el revisor rechaza la solicitud. No consideres la aprobación como una prueba de que la acción propuesta es segura; el revisor aún debe evaluar la solicitud.

Una acción denegada no es una excepción que deba ocultarse. Envía un resultado de “no realizada”, conserva el diagnóstico y ofrece un siguiente paso seguro, como escalar el incidente o realizar otra comprobación de solo lectura.

Gestión de fallos útil para quien está de guardia

Cada ruta de incidente debería terminar con una resolución útil:

• Validación superada: registra la observación y cierra la comprobación sin generar un incidente.
• Señal no saludable: envía las evidencias y el diagnóstico, indicando claramente la incertidumbre.
• Fallo del paso de diagnóstico: informa de qué consulta falló; no presentes los datos ausentes como un resultado negativo.
• Aprobación denegada: indica que no se aplicó la corrección e identifica al siguiente responsable o la siguiente decisión.
• Acción aprobada fallida: informa del error de la herramienta y conserva el contexto original del incidente.

Incluye una clave de deduplicación, como el servicio más la ventana del incidente, si las comprobaciones repetidas podrían saturar un canal. Decide durante cuánto tiempo agrupar las alertas repetidas según tus prácticas de monitorización; este patrón de flujo no prescribe un intervalo universal. Prueba también los tiempos de espera agotados, los estados que no indican éxito, las respuestas con formato incorrecto, la ausencia de datos de diagnóstico, la denegación y el fallo de corrección antes de confiar en el flujo.

Lista de comprobación reutilizable

• ¿Se pueden distinguir los errores de transporte, los errores HTTP y los cuerpos de respuesta no válidos?
• ¿Cada alerta muestra el comportamiento esperado frente al observado y una marca de tiempo?
• ¿Se han excluido los secretos y los datos personales o de clientes innecesarios?
• ¿Las explicaciones generadas por IA están etiquetadas como hipótesis cuando la evidencia es incompleta?
• ¿Las herramientas que cambian el estado están sometidas a revisión humana, con los parámetros visibles para el revisor?
• ¿La denegación de aprobación y el fallo de una herramienta se registran como resultados explícitos?
• ¿Has probado cada rama de fallo, no solo la ruta saludable?

El diseño fiable no consiste en que la “IA corrija incidentes de API”. Consiste en un flujo que hace observables los fallos, usa la IA para organizar las evidencias y mantiene los cambios con consecuencias bajo control humano.