Integración segura con APIs de terceros: reintentos, timeouts y circuit breakers

Por qué las APIs de terceros pueden bloquear tus flujos principales

Una API de terceros puede fallar de maneras que no parecen un evento "caído" limpio. El problema más común es la lentitud: las solicitudes se quedan colgadas, las respuestas llegan tarde y tu app sigue esperando. Si esas llamadas están en el camino crítico, un pequeño tropiezo fuera de tu control se acumula dentro de tu sistema.

Así es como una desaceleración local se convierte en una caída completa. Hilos o workers quedan esperando, las colas crecen, las transacciones de base de datos permanecen abiertas más tiempo y las nuevas solicitudes empiezan a expirar. En poco tiempo, incluso páginas que no usan la API externa se sienten rotas porque el sistema está sobrecargado por trabajo en espera.

El impacto es concreto. Un proveedor de identidad inestable bloquea registros e inicios de sesión. Un timeout en la pasarela de pagos congela el checkout, dejando a los usuarios sin saber si se les cobró. Un retraso en mensajería detiene restablecimientos de contraseña y confirmaciones de pedido, lo que desencadena una segunda ola de reintentos y tickets de soporte.

El objetivo es simple: aislar las fallas externas para que los flujos principales sigan avanzando. Eso puede significar permitir que un usuario realice un pedido mientras confirmas el pago más tarde, o aceptar un registro aunque falle el envío del correo de bienvenida.

Una métrica práctica de éxito: cuando un proveedor está lento o caído, tu app debe seguir respondiendo rápido y de forma clara, y el radio de impacto debe mantenerse pequeño. Por ejemplo, la mayoría de las solicitudes principales aún terminan dentro de tu presupuesto de latencia normal, las fallas se mantienen confinadas a las funciones que realmente dependen de esa API, los usuarios ven un estado claro (en cola, pendiente, inténtalo más tarde) y la recuperación ocurre automáticamente cuando el proveedor vuelve.

Los modos de fallo para los que debes planear

La mayoría de las fallas son previsibles, aunque no lo sea su momento. Nómbralas desde el principio y podrás decidir qué reintentar, qué detener y qué mostrar al usuario.

Categorías comunes:

• Picos de latencia (solicitudes que de repente tardan 10x más)
• Errores transitorios de servidor o red (timeouts, 502/503, reinicios de conexión)
• Límites de tasa y agotamiento de cuota (429s, límites diarios)
• Problemas de autenticación y permisos (claves expiradas, acceso revocado)
• Datos malos o sorprendentes (campos faltantes, formatos incorrectos, respuestas parciales)

No todos los errores significan lo mismo. Los problemas transitorios suelen merecer reintentos porque la siguiente llamada puede tener éxito (interrupciones de red, timeouts, 502/503 y algunos 429s después de esperar). Los problemas permanentes normalmente no se solucionan solos (credenciales inválidas, endpoints equivocados, solicitudes mal formadas, denegaciones de permiso).

Tratar todos los errores igual convierte un incidente pequeño en tiempo de inactividad. Reintentar fallas permanentes desperdicia tiempo, consume límites de tasa más rápido y crea un backlog que ralentiza todo lo demás. No reintentar fallas transitorias obliga a los usuarios a repetir acciones y descarta trabajo que podría completarse momentos después.

Presta atención extra a flujos donde una pausa se siente como una ruptura: checkout, inicio de sesión, restablecimiento de contraseña y notificaciones (email/SMS/push). Un pico de dos segundos en una API de marketing es molesto. Un pico de dos segundos en la autorización de pago bloquea ingresos.

Una prueba útil es: "¿Esta llamada es necesaria para terminar la tarea principal del usuario ahora mismo?" Si la respuesta es sí, necesitas timeouts estrictos, reintentos cuidados y un camino de fallo claro. Si no, muévela a una cola y mantén la app responsiva.

Timeouts: elige un límite y cúmplelo

Un timeout es el tiempo máximo que estás dispuesto a esperar antes de parar y seguir adelante. Sin un límite claro, un proveedor lento puede acumular solicitudes en espera y bloquear trabajo importante.

Ayuda separar dos tipos de espera:

• Connect timeout: cuánto tiempo intentarás establecer la conexión.
• Read timeout: cuánto esperarás por una respuesta después de conectar.

Elegir números no es cuestión de perfección. Es cuestión de coincidir con la paciencia humana y tu flujo de trabajo.

• Si un usuario está mirando un spinner, normalmente necesitas una respuesta rápida y un siguiente paso claro.
• Si es un trabajo en segundo plano (por ejemplo sincronizar facturas durante la noche), puedes permitir más tiempo, pero aún necesita un techo para que no cuelgue para siempre.

Una forma práctica de elegir timeouts es trabajar hacia atrás desde la experiencia:

• ¿Cuánto puede esperar un usuario antes de que necesites mostrar un mensaje claro?
• Si esta llamada falla ahora, ¿puedes reintentar más tarde o usar un fallback?
• ¿Cuántas de estas llamadas se ejecutan en carga pico?

El intercambio es real. Demasiado largo y consumes hilos, workers y conexiones a BD. Demasiado corto y creas fallos falsos y desencadenas reintentos innecesarios.

Reintentos que no empeoran las caídas

Los reintentos ayudan cuando una falla probablemente es temporal: un breve problema de red, un fallo de DNS o un 500/502/503 puntual. En esos casos, un segundo intento puede tener éxito y los usuarios no lo notan.

El riesgo es una tormenta de reintentos. Cuando muchos clientes fallan a la vez y todos reintentan simultáneamente, pueden sobrecargar al proveedor (y a tus propios workers). Backoff y jitter evitan eso.

Un presupuesto de reintentos te mantiene honesto. Mantén los intentos bajos y limita el tiempo total para que los flujos principales no queden esperando a otro servicio.

Una receta de reintento segura por defecto

• Reintenta solo unas pocas veces (a menudo 1-3 intentos en total, dependiendo del flujo).
• Usa backoff exponencial (por ejemplo 200 ms, 500 ms, 1 s) más jitter aleatorio.
• Limita el tiempo total dedicado a reintentos (a menudo unos pocos segundos en flujos de cara al usuario).
• Usa un timeout por intento en lugar de un único timeout largo para todos los intentos.

No reintentes errores predecibles del cliente como 400/422 (validación), 401/403 (auth) o 404s. Esos casi siempre fallarán de nuevo y solo añaden carga.

Una protección más: reintenta escrituras (POST/PUT) solo cuando tengas idempotencia en su lugar; de lo contrario corres el riesgo de cargos dobles o registros duplicados.

Idempotencia: haz los reintentos seguros para flujos reales

Idempotencia significa que puedes ejecutar la misma solicitud dos veces y obtener el mismo resultado final. Eso importa porque los reintentos son normales: las redes se caen, los servidores se reinician y los clientes expiran. Sin idempotencia, un reintento "útil" crea duplicados y problemas reales de dinero.

Imagina un checkout: la API de pago es lenta, tu app expira y reintenta. Si la primera llamada en realidad tuvo éxito, el reintento puede crear un segundo cargo. El mismo riesgo aparece en acciones como crear un pedido, iniciar una suscripción, enviar un email/SMS, emitir un reembolso o crear un ticket de soporte.

La solución es adjuntar una clave de idempotencia (o ID de solicitud) a cada llamada de "hacer algo". Debe ser única por acción del usuario, no por intento. El proveedor (o tu propio servicio) usa esa clave para detectar duplicados y devolver el mismo resultado en vez de ejecutar la acción otra vez.

Trata la clave de idempotencia como parte del modelo de datos, no como un header que esperas que nadie olvide.

Un patrón que funciona en producción

Genera una clave cuando el usuario inicia la acción (por ejemplo, al hacer clic en Pagar), y guárdala con tu registro local.

En cada intento:

• Envía la misma clave.
• Guarda el resultado final que recibiste (respuesta de éxito, código de fallo, ID de cargo).
• Si ya tienes un resultado registrado, devuelve ese resultado en vez de repetir la acción.

Si tú eres el "proveedor" para llamadas internas, aplica el mismo comportamiento en el servidor.

Circuit breakers: deja de llamar a la API cuando está fallando

Un circuito breaker es un interruptor de seguridad. Cuando un servicio externo empieza a fallar, dejas de llamarlo por un breve periodo en vez de acumular más solicitudes que probablemente expiren.

Los circuit breakers suelen tener tres estados:

• Closed: las solicitudes fluyen con normalidad.
• Open: las llamadas están bloqueadas durante una ventana de enfriamiento.
• Half-open: después del enfriamiento, un pequeño número de llamadas de prueba comprueban si el servicio se recuperó.

Cuando el breaker está abierto, tu app debe hacer algo predecible. Si una API de validación de direcciones está caída durante el registro, acepta la dirección y márcala para revisión posterior. Si una verificación de riesgo de pago está caída, encola el pedido para revisión manual o desactiva temporalmente esa opción y explícalo.

Elige umbrales que coincidan con el impacto en el usuario:

• errores consecutivos (por ejemplo 5 fallos seguidos)
• alta tasa de fallos en una ventana corta
• muchas respuestas lentas (timeouts)
• códigos de estado específicos (como 503 repetidos)

Mantén los enfriamientos cortos (segundos a un minuto) y limita las sondas half-open. El objetivo es proteger primero los flujos principales y luego recuperarse rápidamente.

Fallbacks y colas: mantén la app usable

Cuando una API externa está lenta o caída, tu objetivo es mantener al usuario en movimiento. Eso significa tener un Plan B honesto sobre lo que ocurrió.

Fallbacks: elige una experiencia "suficientemente buena"

Un fallback es lo que hace tu app cuando la API no puede responder a tiempo. Las opciones incluyen usar datos en caché, cambiar a un modo degradado (ocultar widgets no esenciales, desactivar acciones opcionales), pedir entrada al usuario en lugar de llamar a la API (entrada manual de dirección) o mostrar un mensaje claro con el siguiente paso.

Sé honesto: no digas que algo se completó si no fue así.

Colas: hazlo después cuando "ahora" no sea necesario

Si el trabajo no necesita terminar dentro de la solicitud del usuario, empújalo a una cola y responde rápido. Candidatos comunes: enviar correos, sincronizar con un CRM, generar informes y publicar eventos de analytics.

Falla rápido para acciones críticas. Si una API no es necesaria para completar el checkout (o la creación de cuenta), no bloquees la solicitud. Acepta el pedido, encola la llamada externa y concilia más tarde. Si la API es necesaria (por ejemplo autorización de pago), falla rápido con un mensaje claro y no hagas esperar al usuario.

Lo que el usuario vea debe coincidir con lo que ocurre detrás: un estado claro (completado, pendiente, fallado), una promesa que puedas cumplir (recibo ahora, confirmación después), una forma de reintentar y un registro visible en la UI (registro de actividad, indicador de pendiente).

Límites de tasa y carga: evita fallos autoinfligidos

Los límites de tasa son la forma que tiene un proveedor de decir: "Puedes llamarnos, pero no demasiado seguido." Los alcanzarás antes de lo que piensas: picos de tráfico, jobs en segundo plano que se disparan juntos o un bug que hace un loop sobre errores.

Empieza controlando cuántas solicitudes creas. Agrupa cuando sea posible, cachea respuestas incluso 30–60 segundos cuando sea seguro y limita en el cliente para que tu app no explote más rápido de lo que el proveedor permite.

Cuando recibas un 429 Too Many Requests, trátalo como una señal para reducir la velocidad.

• Respeta Retry-After cuando esté presente.
• Añade jitter para que muchos workers no reintenten al mismo momento.
• Limita los reintentos para 429s para evitar bucles sin fin.
• Retrocede más agresivamente ante 429s repetidos.
• Regístralo como métrica para notar patrones antes que los usuarios.

También limita la concurrencia. Un solo flujo (como sincronizar contactos) no debería consumir todos los workers y dejar sin recursos flujos críticos como login o checkout. Pools separados o límites por función ayudan.

Paso a paso: una receta de integración segura por defecto

Cada llamada a un tercero necesita un plan para fallar. No necesitas perfección. Necesitas un comportamiento predecible cuando el proveedor tenga un mal día.

1) Clasifica la llamada (imprescindible vs puede esperar)

Decide qué ocurre si la llamada falla ahora mismo. Un cálculo de impuestos durante el checkout puede ser imprescindible. Sincronizar un contacto de marketing normalmente puede esperar. Esta elección guía el resto.

2) Establece timeouts y un presupuesto de reintentos

Elige timeouts por tipo de llamada y mantenlos consistentes. Luego define un presupuesto de reintentos para no seguir golpeando una API lenta.

• Imprescindible, usuario esperando: timeout corto, 0-1 reintentos.
• Puede esperar, trabajo en segundo plano: timeout más largo, algunos reintentos con backoff.
• Nunca reintentar para siempre: limita el tiempo total por tarea.

3) Haz los reintentos seguros con idempotencia y seguimiento

Si una solicitud puede crear algo o cobrar dinero, añade claves de idempotencia y guarda un registro de la solicitud. Si una petición de pago expira, un reintento no debería cobrar dos veces. El seguimiento también ayuda al soporte a responder: "¿Llegó?"

4) Añade un circuito breaker y comportamiento de fallback

Cuando los errores aumentan, deja de llamar al proveedor por un corto periodo. Para llamadas imprescindibles, muestra un camino claro de "Intentar de nuevo". Para llamadas que pueden esperar, encola el trabajo y procésalo después.

5) Monitoriza lo básico

Controla latencia, tasa de errores y eventos de apertura/cierre del breaker. Alerta en cambios sostenidos, no en picos aislados.

Errores comunes que convierten un problema pequeño en tiempo de inactividad

La mayoría de las caídas de APIs no comienzan grandes. Se hacen grandes porque tu app reacciona de la peor manera: espera demasiado, reintenta con demasiada agresividad y ocupa los mismos workers que mantienen todo lo demás en funcionamiento.

Estos patrones causan cascadas:

• Reintentar todo fallo, incluyendo problemas 4xx como solicitudes inválidas, auth expirada o permisos faltantes.
• Configurar timeouts muy largos "para estar seguros", que consumen silenciosamente hilos, conexiones a BD o runners de jobs hasta quedarse sin capacidad.
• Reintentar acciones de creación sin claves de idempotencia, provocando cargos dobles, envíos duplicados o registros repetidos.
• Circuit breakers mal configurados que nunca se recuperan o que se abren y cierran continuamente.
• Tratar fallos parciales como una falla total en vez de degradar solo la característica afectada.

Pequeñas correcciones evitan grandes caídas: reintenta solo errores que probablemente sean temporales (timeouts, algunos 429s, algunos 5xx) y limita intentos con backoff y jitter; mantén timeouts cortos e intencionales; exige idempotencia para cualquier operación que cree o cobre; y diseña para fallos parciales.

Lista rápida antes de lanzar

Antes de poner una integración en producción, haz una pasada rápida con mentalidad de fallo. Si no puedes responder "sí" a un punto, trátalo como blocker de release para flujos críticos como registro, checkout o envío de mensajes.

• Los límites de tiempo son explícitos (connect timeout y read/response timeout).
• Los reintentos están limitados (pequeño presupuesto de reintentos, backoff, jitter y un tope de tiempo total).
• Los reintentos son seguros para acciones reales (claves de idempotencia o comprobaciones claras de deduplicación).
• Hay un breaker y un plan B (fallback, modo degradado o una cola).
• Puedes ver los problemas temprano (latencia, tasa de errores y salud de dependencias por proveedor y endpoint).

Si un proveedor de pagos empieza a expirar, el comportamiento correcto es "el checkout aún carga, el usuario recibe un mensaje claro y no te quedas girando para siempre", no "todo se queda colgado hasta que expira."

Ejemplo: proteger el checkout cuando un proveedor es inestable

Imagina un checkout que llama a tres servicios: una API de pagos para cobrar la tarjeta, una API de impuestos para calcular impuestos y una API de correo para enviar el recibo.

La llamada de pago es la única que debe ser síncrona. Los problemas en impuestos o correo no deberían bloquear la compra.

Cuando la API de impuestos está lenta

Supongamos que la API de impuestos a veces tarda 8 a 15 segundos. Si el checkout espera, los usuarios abandonan el carrito y tu app consume workers.

Un flujo más seguro:

• Establece un timeout estricto (por ejemplo 800 ms a 2 s) y falla rápido.
• Reintenta como mucho una vez, solo si es seguro, con jitter.
• Si se alcanza el timeout, usa una tarifa en caché o la última tabla conocida para la región del comprador.
• Si no puedes usar tarifas en caché por cuestiones legales, marca el pedido como "impuesto pendiente" y encola una recalculación.

Resultado: menos carritos abandonados y menos pedidos atascados cuando el proveedor de impuestos está lento.

Cuando la API de correo está caída

El correo de recibo importa, pero nunca debe bloquear la captura de pago. Si la API de correo está fallando, el circuit breaker debería abrirse tras unos pocos fallos rápidos y detener las llamadas por una ventana de enfriamiento corta.

En lugar de enviar el correo en línea, encola un job de "enviar recibo" con una clave de idempotencia (por ejemplo order_id + email_type). Si el proveedor está caído, la cola reintentará en segundo plano y el cliente verá la compra como exitosa.

Resultado: menos tickets de soporte por confirmaciones faltantes y cero pérdida de ingresos por fallos en servicios no relacionados con el pago.

Próximos pasos: desplegar esto con seguridad en tu app

Elige un flujo que más duela cuando falla (checkout, registro, facturación) y hazlo tu integración de referencia. Luego copia los mismos valores por todas partes.

Un orden simple para desplegar:

• Establece timeouts y falla rápido con un error claro.
• Añade reintentos con backoff, pero solo para errores reintentables.
• Añade idempotencia para que los reintentos no dupliquen cargos o creaciones.
• Añade circuit breakers para que un proveedor malo no deje bloqueado tu flujo principal.

Escribe tus valores predeterminados y mantenlos aburridos: un connect timeout, un request timeout, conteo máximo de reintentos, rango de backoff, tiempo de enfriamiento del breaker y las reglas de qué es reintentable.

Ejecuta un simulacro de fallo antes de expandir al siguiente flujo. Fuerza timeouts (o bloquea al proveedor en un entorno de prueba), luego confirma que el usuario ve un mensaje útil, los fallbacks funcionan y los reintentos en cola no se acumulan para siempre.

Si estás construyendo productos nuevos rápidamente, vale la pena convertir estos valores por defecto de fiabilidad en una plantilla reutilizable. Para equipos que usan Koder.ai (koder.ai), eso a menudo significa definir el timeout, reintentos, idempotencia y reglas de breaker una vez, y luego aplicar el mismo patrón en nuevos servicios mientras los generas e iteras.