En este paso diseñas qué pasa cuando algo falla, porque va a fallar: APIs caídas, rate limits, tokens vencidos, datos sucios. Una integración seria reintenta sola, no duplica al reintentar y aparta en una cola revisable lo que no puede resolver. Esta es la diferencia entre la demo y la producción.
Clasifica los errores antes de manejarlos
No todos los errores se tratan igual. Tres familias, tres respuestas:
- Transitorios (timeouts, HTTP 429, 500/503): el problema es del momento, no del dato. Se reintentan automáticamente.
- Permanentes (HTTP 400, validación: email inválido, campo obligatorio vacío, SKU inexistente): reintentar mil veces da mil veces el mismo error. Van directo a la cola de revisión con su motivo.
- De autenticación (401/403, token vencido, permisos revocados): frenan TODO el flujo, no un registro. Renovación automática si se puede, alerta inmediata siempre.
Tratar un error permanente como transitorio desperdicia recursos; tratar uno transitorio como permanente pierde datos que se habrían salvado solos.
Reintentos con backoff exponencial (y un poco de azar)
El patrón estándar: esperar 1 minuto, luego 5, luego 25… duplicando o quintuplicando el intervalo, con un tope de 5 a 7 intentos. Dos refinamientos que separan lo casero de lo profesional:
- Jitter: súmale un azar pequeño a cada espera. Si 500 registros fallaron juntos y reintentan juntos, tumban la API otra vez: el estampido de la manada.
- Respeta el "Retry-After": cuando la API te dice cuánto esperar (los 429 de HubSpot o Shopify lo traen), obedece. Reintentar antes solo alarga el castigo.
Y presupuesta los límites desde el diseño: si tu flujo mueve picos de miles de registros —un Black Friday, un cierre de mes—, el throttling no es un edge case, es el martes. Un ecommerce mexicano que atendimos perdía el 8% de sus pedidos justo en campañas: la integración funcionaba perfecto los días tranquilos y se ahogaba exactamente cuando más vendía. El backoff con jitter lo resolvió en una semana.
Idempotencia: reintentar sin duplicar
El peligro oculto del reintento: la escritura llegó, la respuesta se perdió, el sistema reintenta y ahora el pedido existe dos veces. La vacuna es la idempotencia: que ejecutar la misma operación dos veces deje el mismo resultado que una.
En la práctica: upsert por ID externo (la llave del paso 4) en lugar de "crear"; llaves de idempotencia cuando la API las soporta; verificar existencia antes de escribir cuando no. Si tus reintentos no son idempotentes, no tienes manejo de errores: tienes un generador de duplicados con buenas intenciones.
La cola de mensajes muertos: donde nada se pierde en silencio
Lo que agotó sus reintentos o falló de forma permanente no se descarta: cae en una dead-letter queue con el payload completo, el motivo del fallo y la fecha. Tres reglas la hacen útil:
- Tiene un dueño humano con SLA: alguien la revisa en menos de 48 horas.
- Permite reprocesar: corriges el dato y lo reinyectas, sin tickets a ingeniería.
- Se alerta por patrón, no por evento: "40 registros fallaron por el mismo campo en una hora" es una alerta; cada registro individual es ruido que entrena al equipo a ignorar alertas.
La diferencia entre una integración amateur y una profesional no es que no falle: es lo que hace en los cinco minutos siguientes a fallar.
Errores comunes en este paso
- Reintentar todo por igual. Los errores de validación no se curan con insistencia; saturan la cola y esconden los problemas reales.
- Reintentos sin idempotencia. Cada timeout se convierte en un posible duplicado. El paso 4 existía por algo.
- Alertar por cada error individual. A la tercera semana nadie lee las alertas, incluida la importante.
- Descartar en silencio. El registro que "se perdió" hoy es la factura que contabilidad busca a fin de mes.
Checklist antes de pasar al siguiente
- Errores clasificados (transitorio / permanente / autenticación) con manejo distinto por clase.
- Backoff exponencial con jitter, tope de intentos y respeto del Retry-After.
- Escrituras idempotentes: upsert por ID externo en todos los flujos.
- Dead-letter queue con payload, motivo, dueño humano y SLA de revisión.
- Alertas por patrón configuradas, no por evento individual.
- Simulacro de caída ejecutado en sandbox: apaga la API destino 30 minutos y mira qué pasa.
Tu integración ya aguanta golpes. Falta el último paso para dormir tranquilo: paso 7, monitoreo. O repasa el plan completo en la guía de integración de datos.