Patrón circuit breaker para APIs de terceros en flujos visuales

Por qué las caídas de APIs de terceros rompen más de una funcionalidad

Una sola API de terceros suele estar en el centro del trabajo diario: cobrar pagos, validar direcciones, sincronizar inventario, enviar mensajes, verificar identidad. Cuando ese proveedor tiene problemas, rara vez se rompe solo un botón. Puede congelar flujos enteros que necesitan esa respuesta para avanzar.

Por eso un circuit breaker importa. No es teoría: es una forma práctica de mantener las operaciones centrales funcionando incluso cuando una integración está enferma.

Lento y caído dañan de maneras diferentes.

Cuando una API es lenta, tu flujo todavía intenta tener éxito, pero cada paso espera. Los usuarios ven pantallas con carga continua, los equipos de soporte reciben tickets de “está atascado” y los jobs en background se acumulan. Lo lento es engañoso porque puede parecer que tu propio sistema está fallando.

Cuando una API está caída, obtienes timeouts o errores duros. Eso es más claro, pero a menudo más peligroso porque los flujos tienden a reintentar. Cuando muchas solicitudes reintentan a la vez, creas una tormenta de tráfico que dificulta la recuperación y puede arrastrar tu propio sistema.

Los síntomas habituales aparecen rápido: timeouts, colas que siguen creciendo, actualizaciones parciales y mucho trabajo manual para limpiar.

El daño real es la reacción en cadena. Si un proveedor de tarifas de envío está lento, la colocación de pedidos se retrasa porque el flujo se niega a confirmar el pedido sin la cotización. Si los pagos están caídos, el soporte puede verse bloqueado para emitir reembolsos aunque todo lo demás funcione.

No puedes fingir que las caídas no existen. El objetivo es diseñar flujos con rutas de fallback claras, reglas de bloqueo temporal y alertas para que el negocio pueda seguir tomando pedidos, atendiendo clientes y registrando trabajo mientras la integración se recupera.

Circuit breaker en términos sencillos

Un circuit breaker es un interruptor de seguridad para llamadas a APIs. Cuando un servicio de terceros empieza a fallar, el breaker evita que tu flujo lo golpee una y otra vez. En vez de convertir una caída en pantallas lentas, timeouts y jobs atascados, controlas el radio del daño.

Un circuit breaker tiene tres resultados simples:

• Permitir la llamada cuando el proveedor parece saludable.
• Bloquear la llamada cuando las fallas son altas y tomar inmediatamente una ruta de fallback.
• Intentar una llamada de prueba limitada después de una breve pausa para ver si el proveedor volvió.

Si prefieres etiquetas, son “closed”, “open” y “half-open”. Los nombres no son lo importante: lo es la previsibilidad. Cuando un proveedor está enfermo, tu flujo debería comportarse igual cada vez.

Esto no oculta errores. Aun así registras fallos, muestras un estado claro a usuarios u operaciones y alertas a las personas adecuadas. Estás eligiendo fallar rápido, enrutar trabajo a una alternativa más segura o pausar brevemente antes de volver a probar.

Elige qué llamadas de API nunca deben detener el negocio

Los circuit breakers funcionan mejor cuando eres selectivo. No toda llamada a un proveedor merece protección especial. Empieza por pasos que, si se bloquean, detienen dinero, pedidos o acceso de clientes.

Un método práctico es seguir una solicitud de usuario de extremo a extremo. ¿Dónde forzaría un timeout al usuario a abandonar la tarea, o crearía un lío que tu equipo tiene que limpiar después?

Llamadas típicas que “no deben bloquear trabajo crítico” incluyen pagos, envíos y cumplimiento, login/SSO/MFA, OTP y mensajes de confirmación, y verificaciones de cumplimiento ligadas a aprobaciones.

También separa pasos que ven usuarios de jobs en background. Si alguien espera en una pantalla de checkout necesitas una decisión rápida: éxito, fallback o detención con un mensaje claro. Para trabajo en background como sincronizar números de seguimiento, reintentos más lentos están bien siempre que no bloqueen el flujo principal.

Empieza pequeño para evitar que el alcance crezca. Protege 1–3 flujos primero, luego expande.

Define qué significa “fallback seguro” antes de construir nada. Los buenos fallbacks son específicos y comprobables:

• Pagos: guarda el pedido como “pago pendiente” para no perder el carrito.
• Envío: usa una tarifa en caché, una tarifa plana o confirma el pedido y retrasa la compra de la etiqueta.
• Identidad: permite login por contraseña cuando SSO está caído, o cambia a verificación por email.
• Mensajería: encola el SMS para más tarde y ofrece una ruta alternativa cuando sea posible.

En AppMaster’s Business Process Editor, esto suele convertirse en una rama limpia: la operación principal continúa, mientras que el paso dependiente del proveedor toma una alternativa controlada.

Estados, umbrales y temporizadores que puedes explicar

Un circuit breaker es un interruptor de seguridad. La mayoría del tiempo deja pasar las llamadas. Cuando el proveedor empieza a fallar, se activa para proteger tu flujo del tiempo perdido y la acumulación de errores.

Los tres estados

Closed es lo normal. Llamas a la API y continúas.

Si las fallas cruzan una línea, el breaker pasa a Open. Dejas de llamar al proveedor por un periodo corto y enrutás inmediatamente a un fallback (valor en caché, trabajo en cola, flujo alterno).

Tras un periodo de enfriamiento, el breaker pasa a Half-open. Permites un pequeño número de llamadas de prueba. Si tienen éxito, vuelves a Closed. Si fallan, vuelves a Open.

Qué medir

Usa señales que coincidan con cómo falla el proveedor:

• Timeouts
• Errores HTTP 5xx
• Latencia en aumento (demasiado lenta para ser útil)
• Errores de conexión/DNS
• 429 límites de tasa

En una herramienta de flujo visual, esto suele mapearse a cheques simples: código de estado, tiempo transcurrido y salidas de error específicas.

Umbrales iniciales y los dos temporizadores clave

Empieza con números fáciles de explicar y ajústalos con el tiempo. Ejemplos:

• Abrir el breaker si 5–10 llamadas fallan en 30–60 segundos.
• O abrir si 20%–40% de las llamadas fallan en una ventana rodante.
• Trata la latencia como fallo cuando excede lo tolerable para tu proceso (a menudo 2–5 segundos).

Luego configura dos temporizadores:

• Tiempo de enfriamiento (estado Open): suele ser de 30 segundos a 5 minutos.
• Ventana de prueba Half-open: permite 1–5 llamadas de prueba, o una ventana breve como 10–30 segundos.

El objetivo es claro: fallar rápido cuando el proveedor está malsano y recuperarse automáticamente cuando vuelva.

Paso a paso: construir un circuit breaker en un flujo visual

La decisión de diseño más importante es decidir “¿debemos llamar al proveedor ahora?” en un solo lugar, no dispersa en cada flujo.

1) Pon la llamada al proveedor detrás de un bloque reutilizable

Crea un subproceso (un bloque de flujo reutilizable) que cada flujo use cuando necesite ese proveedor. En AppMaster, esto mapea naturalmente a un Business Process que puedes llamar desde endpoints o automatizaciones. Manténlo estrecho: entradas dentro, petición al proveedor fuera, más un resultado claro de éxito/fallo.

2) Registra fallos por tiempo, no solo por conteo

Registra cada resultado con su marca temporal. Guarda cosas como última respuesta exitosa, último fallo, fallos dentro de una ventana, estado actual y un plazo de cooldown.

Persiste estos campos en una tabla para que el breaker sobreviva reinicios y sea consistente entre instancias múltiples. PostgreSQL vía Data Designer encaja bien para esto.

3) Define cambios de estado que seguirás siempre

Mantén las reglas simples. Ejemplo: si 5 fallos ocurren en 2 minutos, cambia a Open. Mientras esté Open, omite la llamada al proveedor hasta que pase el cooldown. Tras el cooldown, pasa a Half-open y permite un intento controlado. Si funciona, cierra el breaker. Si falla, ábrelo otra vez.

4) Divide el flujo: camino del proveedor vs ruta de fallback

Antes de la petición al proveedor, chequea el estado almacenado:

• Closed: llama al proveedor y luego actualiza éxito o fallo.
• Open: omite la llamada y ejecuta el fallback.
• Half-open: permite un intento limitado y luego decide si cerrar o reabrir.

Ejemplo: si una API de etiquetas de envío está caída, el fallback puede crear el pedido con estado “Label pending” y encolar un job de reintento, en lugar de bloquear el checkout o el trabajo del almacén.

5) Hazlo compartido entre flujos

Si tienes múltiples flujos y servidores, deben leer y escribir el mismo estado del breaker. Si no, una instancia puede seguir golpeando al proveedor mientras otra ya decidió pausar.

Rutas de fallback que mantienen el trabajo en movimiento

Un circuit breaker solo ayuda si decides qué pasa cuando la llamada está bloqueada. Un buen fallback mantiene al usuario avanzando, protege tus datos y hace que la limpieza posterior sea predecible.

Elige un fallback que corresponda con la tarea. Si un proveedor de tarifas de envío está caído, puede que no necesites un precio exacto para aceptar el pedido. En un flujo visual, enruta el paso de API fallido a una rama de fallback que aún produzca un resultado usable.

En la práctica, los fallbacks suelen ser uno de estos:

• Usar un valor último conocido en caché (con una ventana de frescura clara).
• Usar una estimación segura por defecto, etiquetada claramente.
• Enrutar a revisión manual.
• Encolar el trabajo para reintentos posteriores (job asíncrono).

La experiencia de usuario importa tanto como la lógica. No muestres un error vago. Di qué pasó y qué puede hacer el usuario: “No pudimos confirmar la tarifa ahora. Puedes realizar el pedido con un costo estimado de envío, o guardarlo para revisión.”

También planifica para cortes cortos vs largos. Una caída corta (minutos) suele significar “seguir adelante y reintentar en background”. Una caída larga (horas) puede requerir comportamientos más estrictos como más revisiones manuales o aprobaciones.

Finalmente, registra cada fallback para que la conciliación sea fácil. Como mínimo, guarda el tipo de fallback, detalles de la petición original, qué se devolvió al usuario (y si fue una estimación) y un estado para seguimiento.

Reglas de bloqueo temporal y reintentos más inteligentes

Los reintentos sin control convierten pequeños fallos del proveedor en verdaderas caídas. Cuando muchos flujos reintentan al mismo tiempo, crean un pico (el problema de la “manada estruendosa”). El proveedor se vuelve más lento, tus colas crecen y consumes límites de tasa.

Los reintentos deben ser predecibles y limitados, y deben respetar el estado del breaker. Una política práctica es:

• Mantén los reintentos máximos bajos (a menudo 2–3).
• Usa backoff exponencial (por ejemplo, 2s, 8s, 30s).
• Añade jitter para que los reintentos no se sincronicen.
• Limita el tiempo total de reintentos (por ejemplo, 60–90 segundos).
• Si el breaker está Open, no reintentes. Ve directo al fallback.

El bloqueo temporal está relacionado pero es distinto. Es para casos donde la respuesta te dice “esto no funcionará ahora”. Reglas comunes:

• 429 límite de tasa: bloquear por el periodo Retry-After (o una ventana segura fija).
• 401/403 fallo de auth: bloquear hasta que las credenciales se renueven, luego probar una vez.
• 5xx consistentes: bloquear brevemente y luego permitir una pequeña prueba.

Durante un bloqueo, decide qué pasa con el trabajo ya en curso: encolarlo, reenrutarlo o degradarlo con gracia (por ejemplo, aceptar el pedido pero retrasar “enviar SMS”).

Alertas que te dicen qué hacer

Un circuit breaker solo ayuda si la gente se entera rápido y sabe qué hacer. El objetivo no es ruido: es un mensaje claro cuando el comportamiento cambia: se están bloqueando llamadas, los fallbacks están activos o el breaker ha permanecido abierto más de lo esperado.

Buenos disparadores por defecto:

• Alertar cuando el breaker se abre.
• Alertar si permanece abierto más allá de un límite de tiempo.
• Alertar ante un aumento brusco de errores incluso antes de abrir.

Haz las alertas accionables. Incluye el proveedor y endpoint, estado actual y cuándo cambió, qué sentirán los usuarios, qué está haciendo el flujo ahora (bloqueando, reintentando, fallback) y un paso sugerido.

Enruta alertas por severidad. Una API no crítica puede ir por email. Pagos, login o envío de pedidos suelen merecer una página. En AppMaster esto se mapea limpiamente a ramas que envían email, Telegram o SMS según una bandera de severidad.

Mide un conjunto pequeño de métricas para ver la recuperación: llamadas bloqueadas y uso de fallbacks por proveedor suelen ser suficientes.

Escenario de ejemplo: caída del proveedor sin detener pedidos

Un fallo común: el proveedor de tarifas de envío cae justo cuando los clientes están en checkout. Si tu flujo exige tarifas en vivo durante la creación del pedido, una sola caída puede detener completamente los pedidos.

En un día normal, el pedido se crea, luego el flujo solicita tarifas en vivo y el pedido se guarda con el carrier y precio elegidos.

Cuando el proveedor empieza a fallar, las llamadas hacen timeout o devuelven 5xx. Una vez que se alcanza tu umbral (por ejemplo, 5 fallos en 2 minutos), el breaker se abre.

Mientras está Open, el flujo deja de llamar al proveedor por una ventana corta (digamos, 10 minutos). Eso evita que un proveedor fallando arrastre el checkout para todos.

En lugar de bloquear el checkout, el fallback puede:

• Aplicar una tarifa plana (o una estimación segura).
• Crear el pedido de todos modos.
• Marcarlo como “Shipping rate pending” para recálculo posterior.
• Guardar detalles del error del proveedor para seguimiento.

En AppMaster, esto es una rama clara en el Business Process Editor, respaldada por campos en Data Designer como shipping_rate_status y shipping_rate_source.

Comprobaciones rápidas antes de lanzar

Un circuit breaker debe comportarse igual bajo carga que en una demo. Antes del lanzamiento, confirma lo básico:

• Los umbrales y cooldowns están documentados y son fáciles de cambiar.
• El estado Open bloquea llamadas inmediatamente (sin esperar timeouts del proveedor).
• El comportamiento de fallback es seguro para dinero y promesas a clientes.
• Las pruebas Half-open están limitadas a pocas llamadas.
• Los logs facilitan responder sobre tiempos e impacto.

Invierte tiempo extra en la seguridad del fallback. Un fallback que “mantiene el trabajo” también puede crear riesgo financiero. Si el proveedor de pagos está caído, marcar pedidos como pagados es peligroso. Un enfoque más seguro es “pago pendiente”, con mensajería clara al cliente.

Prueba la recuperación a propósito. Fuerza fallos, observa que el breaker se abre, espera el cooldown y confirma que Half-open solo envía una pequeña sonda. Si tiene éxito, debe cerrarse rápido. Si falla, debe volver a abrirse sin inundar al proveedor.

Tus logs deberían responder, en menos de un minuto: quién fue afectado, cuándo empezó, qué paso del flujo disparó el breaker y qué fallback se usó.

Siguientes pasos: implementar el patrón en AppMaster

Elige una integración que pueda dañar las operaciones diarias si falla (pagos, etiquetas de envío, SMS, sincronización CRM). Construye el breaker de extremo a extremo para esa llamada primero. Cuando el equipo confíe en el comportamiento, repite la misma plantilla para el siguiente proveedor.

En AppMaster, modela el estado del breaker en PostgreSQL usando Data Designer. Manténlo simple: un registro por proveedor (o endpoint) con campos como state, failure_count, last_failure_at, open_until y un corto last_error.

Luego implementa la lógica en el Business Process Editor con ramas legibles. La claridad vence a la ingeniosidad.

Un orden de construcción práctico:

1. Verifica el estado del breaker y bloquea llamadas cuando open_until esté en el futuro.
2. Llama a la API del proveedor y captura salidas de éxito y error.
3. En éxito, reinicia contadores y cierra el breaker.
4. En fallo, incrementa contadores y abre el breaker cuando se cumplan umbrales.
5. Enruta los flujos orientados al usuario a un fallback (encolar trabajo, usar datos en caché o permitir procesamiento manual).

Documenta la decisión de fallback en lenguaje llano para que soporte y ops sepan qué ven los usuarios.

Cuando el breaker se abra, notifica a un responsable usando los módulos de mensajería de AppMaster (email, SMS, Telegram). Incluye lo que importa: proveedor, endpoint, estado y la primera acción recomendada.

Si estás construyendo estos flujos en AppMaster, appmaster.io es un lugar práctico para comenzar porque el mismo Business Process visual puede alimentar endpoints, jobs en background y alertas con un estado de breaker compartido.