Integrar APIs que fallan: reintentos, idempotencia y backoff

Toda API externa que integres va a fallar. Va a agotar el tiempo de espera, te va a limitar, va a devolver un 500 en pleno despliegue o va a renombrar un campo sin avisar. La pregunta no es si tu integración se va a topar con esas fallas, sino si las maneja a propósito o por accidente.

Dónde lo aprendimos

Estuvimos a cargo de la capa de integraciones y datos de una plataforma de IA para profesionales legales y de salud. Se conectaba con muchos sistemas externos por REST y SOAP/XML, con OAuth2, claves de API y webhooks. Esos sistemas limitan peticiones, agotan tiempos de espera, devuelven datos inconsistentes y cambian sin aviso. Por eso cada llamada tenía reintentos y tiempos límite, patrones de circuit breaker y de límite de peticiones, y registros estructurados con identificadores de correlación, y cada fuente vivía detrás de su propio adaptador.

Decide qué errores reintentar

Reintentar todo está tan mal como no reintentar nada. Clasifica los errores antes de escribir un solo ciclo de reintentos:

• Reintentar: tiempos de espera agotados, conexiones cortadas, 429 Too Many Requests, 502, 503 y 504. Suelen ser temporales.
• No reintentar: 400, 403, 404 y 422. La petición está mal, falta el permiso o el registro no existe; enviarla otra vez no cambia nada. Con un 401, renueva el token una vez y detente.
• Reintentar con cuidado: un 500 o un tiempo agotado en una escritura. Puede que el servidor haya hecho el trabajo antes de fallar. Para eso existe la idempotencia.

Backoff exponencial con jitter

Cuando una llamada falla, espera antes de reintentar, y espera más cada vez, duplicando la pausa hasta un tope. Luego agrega jitter: una cantidad aleatoria en cada espera. Sin eso, todos los procesos que fallaron en el mismo momento reintentan en el mismo momento, y un servidor que ya está en problemas recibe oleadas sincronizadas. Si la API manda un encabezado Retry-After, respétalo.

Presupuestos de reintentos

El backoff por llamada no alcanza. Dale a cada proceso un presupuesto de reintentos: un límite de intentos por llamada y de cuánto de tu tráfico pueden ser reintentos. Cuando se acaba el presupuesto, detente y registra la falla. Los reintentos sin límite convierten una caída parcial en una total.

Circuit breakers y límites de peticiones

Si una fuente sigue fallando, deja de llamarla por un rato. Un circuit breaker se abre después de fallas repetidas, responde con error de inmediato durante un periodo de enfriamiento y después deja pasar una petición de prueba. Combínalo con un límite de peticiones del lado del cliente que se mantenga por debajo de la cuota del proveedor. Una fuente lenta nunca debería frenar a las demás.

Claves de idempotencia en cada escritura

Una escritura reintentada puede crear dos facturas, dos citas o dos notas. Envía una clave de idempotencia con cada escritura: un ID único para la operación, generado una vez y reutilizado en cada reintento, para que el proveedor la aplique una sola vez. Si la API no soporta claves, guárdalas de tu lado y verifica si el registro ya existe antes de escribir de nuevo. Diseña tus propios receptores de webhooks igual: los webhooks llegan más de una vez, y recibir el mismo evento dos veces tiene que ser inofensivo.

Colas de mensajes fallidos

Cuando un registro agotó sus reintentos, no lo descartes ni bloquees la cola detrás de él. Muévelo a una cola de mensajes fallidos (dead-letter queue) con el error, el contenido y el identificador de correlación. Alguien puede revisarlo, corregir la causa y volver a procesarlo. Nada desaparece en silencio.

Procesos de conciliación

Aun con todo lo anterior, algunos cambios se pierden: un webhook que nunca llegó, un registro editado durante una caída. Un proceso de conciliación programado compara tu copia con la fuente, primero conteos de registros y fechas de última actualización, luego los registros que difieren, y repara los huecos.

Detecta cambios de contrato

Las APIs cambian sin aviso. Valida cada respuesta contra la forma que esperas, en el borde del adaptador. Un campo que falta, un valor de estado nuevo o un número que llega como texto debería fallar de forma visible y disparar una alerta, no colarse en silencio en tus datos. Un cambio detectado en la puerta es un arreglo pequeño. Uno que detecta un cliente es un incidente.

Construimos cada integración así porque sale más barato que el primer incidente. Es parte de cómo trabajamos.