Gestión de errores (On Error)
Cualquier componente puede fallar: un servicio que no responde, una clave caducada, un dato que no llega. Por defecto, cuando un componente falla, el flujo se para y la ejecución termina con error. Con la pestaña On Error decides tú qué pasa en cada componente.
Así se configura y así se ve cuando un componente falla:
Dónde está
Abre la configuración de un componente y pulsa la pestaña On Error. La tienen casi todos los componentes. No la tienen los que empiezan o terminan un flujo (Chat Input, Chat Output, Webhook), los que deciden el camino (Conditional Router, Switch, Loop) ni los componentes de voz, que tienen sus propias reglas durante una llamada.
Qué puedes elegir
En On Error eliges qué pasa cuando el componente falla:
- Stop flow: el flujo se para y la ejecución termina con el error. Es lo que pasa siempre si no cambias nada.
- Route to Error output: el componente muestra una salida nueva, Error, en rojo. Si falla, el flujo sigue por lo que hayas conectado a esa salida, y no por las salidas normales. Si funciona, la rama de Error no se ejecuta.
- Continue with default value: si falla, el componente devuelve lo que escribas en Default Value y el flujo sigue como si nada. Puedes escribir un texto o un JSON.
Con Route to Error output, la salida Error entrega:
| Campo | Qué contiene |
|---|---|
error | El mensaje del error, sin claves ni contraseñas |
text | El mismo mensaje, para los componentes que leen el texto (Parse Data con {text}, Chat Output) |
error_type | El tipo de error |
component | El nombre del componente que ha fallado |
component_id | Su identificador en el flujo |
attempts | Cuántas veces se ha intentado |
Si eliges Route to Error output pero no conectas nada a Error, el flujo se para igual que con Stop flow: nadie recoge el error.
Cuándo se considera que un componente ha fallado
On Error actúa cuando el componente falla. Algunos componentes no fallan cuando el servicio contesta con un error: te devuelven la respuesta con el error dentro, para que decidas tú más adelante en el flujo.
- API Request: con On Error en Stop flow, un error del servicio (por ejemplo, un código 500) llega como dato, con su
status_code, como siempre. En cuanto eliges otra opción o pones Retries, una respuesta con código 400 o superior, o una petición que no llega al servicio, cuentan como fallo. - Si un componente te devuelve el error como dato y quieres tratarlo, comprueba ese dato con un Conditional Router después del componente.
Reintentos
- Retries: cuántas veces más se intenta el componente antes de darlo por fallido, de 0 a 5.
- Retry Delay: los segundos que espera antes del primer reintento. Cada reintento espera el doble que el anterior.
Un reintento vuelve a ejecutar el componente entero. Para que nunca se haga dos veces algo que ya se hizo (un correo, un cobro, un registro), solo se reintenta cuando el fallo demuestra que no se llegó a hacer nada:
- No se pudo conectar con el servicio: no existe, no responde o rechaza la conexión.
- El servicio contestó que estaba ocupado y no atendió la petición (errores 429 y 503).
Cualquier otro fallo no se reintenta, aunque hayas puesto Retries: un servicio que tarda demasiado en contestar, un error 500 o un dato incorrecto. En esos casos la petición pudo llegar a procesarse, así que el componente pasa directamente a lo que hayas elegido en On Error.
Tampoco se reintenta un componente que recibe una lista y la procesa entera de una vez, por ejemplo varias direcciones o varios correos: si fallara en el tercero, el reintento volvería a procesar los dos primeros. Para reintentar registro a registro, activa Batch Mode: cada elemento se ejecuta por separado y solo se reintenta el que falla. El panel te avisa debajo de Retries cuando el componente admite Batch Mode y no lo tiene activado.
Los reintentos funcionan con las tres opciones. Con Stop flow y reintentos, el componente se intenta varias veces y, si sigue fallando, el flujo se para.
Cómo se ve cuando ha fallado
Cuando un componente falla y On Error lo gestiona, su icono de estado sale en ámbar en lugar de verde. Pasa el ratón por encima para ver el error y cuántas veces se ha intentado.
La ejecución termina bien, pero el error queda en el registro de la ejecución, en Ejecuciones, como Handled error.
Con Batch Mode
Con Batch Mode, On Error se aplica a cada elemento por separado:
- Con Route to Error output, los elementos que fallan salen por Error y los que funcionan, por la salida normal. Un elemento roto ya no para la lista entera.
- Con Continue with default value, cada elemento que falla devuelve el valor por defecto.
- Los reintentos se hacen elemento a elemento: los elementos que ya salieron bien no se repiten.
Dentro de un Loop
Con Route to Error output dentro de un Loop, las dos ramas (la normal y la de Error) tienen que volver a juntarse antes del Loop End, porque este solo admite una conexión. Únelas con un Merge Data y conecta su salida al Loop End: así, el elemento que falla sigue por la rama de error y el bucle continúa con el siguiente.
Con Continue with default value no hace falta nada más: el elemento que falla devuelve el valor por defecto y el bucle sigue.
Cuando el componente es una herramienta de un agente
Si conectas el componente como herramienta de un agente:
- Los reintentos y el valor por defecto funcionan igual.
- Con Route to Error output, el agente recibe el error como respuesta de la herramienta y decide qué hacer: probar otra cosa, pedir un dato al usuario o explicarle qué ha pasado.
Ejemplos
- Un servicio externo que a veces se satura: Retries a 2 y Retry Delay a 2 segundos.
- Un dato que no es imprescindible: Continue with default value con un texto como “Sin información”.
- Avisar cuando algo falla: Route to Error output y conecta Error a un componente que envíe un correo o un mensaje a tu equipo.