Una integración que espera indefinidamente puede bloquear una compra, una reserva o una tarea interna. Pero fijar un plazo demasiado corto también puede interrumpir operaciones válidas. Por eso, cómo definir timeouts en integraciones no es solo una decisión de configuración: requiere acordar qué puede esperar el negocio, qué experiencia recibirá la persona usuaria y cómo se resolverán los resultados inciertos.
Un timeout limita cuánto tiempo espera un componente por una respuesta. No demuestra que el sistema externo haya detenido su trabajo ni que la operación haya fallado. Diseñar bien estos límites significa decidir qué se espera, cuándo dejar de esperar y qué hacer después.
El plazo debe responder a una necesidad de negocio
Empieza por identificar qué proceso depende de la respuesta externa y qué consecuencia tiene la demora. Una autorización necesaria antes de confirmar una compra no tiene el mismo margen que la actualización de un catálogo que puede completarse en segundo plano. El criterio no debería ser «qué valor se suele usar», sino cuánto puede esperar el proceso sin perjudicar al usuario, la operación o la consistencia de los datos.
Para cada dependencia, aclara:
- Qué decisión está bloqueada: por ejemplo, confirmar una reserva o mostrar un resultado.
- Quién espera: una persona en una pantalla, una API consumidora, un proceso nocturno o un equipo operativo.
- Qué ocurre si no hay respuesta a tiempo: se puede posponer, continuar con información parcial o detener el proceso.
- Qué significa «completado»: que se recibió una respuesta, que el proveedor aceptó la solicitud o que el efecto final quedó confirmado.
Esta última distinción evita confundir una respuesta técnica con el resultado funcional. Un servicio puede aceptar una solicitud sin haber terminado la operación. Si el negocio necesita conocer el resultado final, quizá corresponde consultar su estado o recibir una notificación posterior, no aumentar indefinidamente el tiempo de espera.
Separa los límites de conexión, respuesta y operación
Un solo timeout puede ocultar dónde se acumula la demora. Conviene distinguir límites según el punto de espera y definir una duración máxima total para la operación. Por ejemplo, el intento de establecer una conexión puede tener un límite; la espera de datos después de conectarse, otro; y toda la secuencia —incluidas llamadas dependientes— debe caber dentro de un presupuesto global.
Si hay varios servicios en cadena, el tiempo disponible se reparte entre ellos. No es razonable que cada dependencia consuma por separado el máximo permitido al usuario: la suma puede exceder el plazo del proceso. Propaga un deadline o plazo límite común, y haz que cada componente use solo el tiempo restante. Así, una llamada tardía no sigue trabajando cuando la operación que la originó ya perdió su utilidad.
Los nombres y el comportamiento de los límites varían entre bibliotecas y plataformas. Comprueba si el valor configurado cubre solo la conexión, la lectura de una respuesta, cada intento o la operación completa. También revisa si hay proxies, balanceadores o clientes intermedios con límites propios; el plazo efectivo suele ser el más restrictivo de la ruta.
El contexto importa. Una interacción de usuario suele requerir una respuesta rápida o una transición clara a un estado pendiente. Un proceso por lotes puede aceptar una ventana mayor, siempre que tenga supervisión y límites. En ambos casos, establece el plazo a partir de objetivos del proceso y de datos observados de latencia, no de un valor arbitrario.
Al vencer el plazo, elige entre cancelar, esperar o degradar
El timeout debe activar una decisión prevista, no una excepción sin tratamiento. Hay tres patrones habituales, que pueden combinarse según la operación:
- Cancelar y detener la espera: útil cuando la respuesta ya no aporta valor. Propaga la cancelación a las tareas en curso si el cliente y el servicio lo permiten, y libera recursos locales.
- Dejar la operación pendiente: adecuado si el proveedor puede procesar el trabajo de forma asíncrona. Devuelve o registra una referencia de seguimiento y permite consultar el estado después.
- Continuar de forma degradada: válido cuando existe una alternativa segura, como mostrar datos recientes o posponer una actualización. Comunica qué parte no se pudo completar y evita presentar información provisional como confirmada.
Cancelar la espera no equivale a deshacer la operación remota. Una solicitud puede haber llegado al proveedor justo antes de que el cliente agotara su plazo. El servidor puede seguir procesándola aunque la conexión se cierre. Por eso, no marques automáticamente la acción como fallida ni confirmes al usuario que nada ocurrió sin evidencia suficiente.
Si el efecto no puede quedar en un estado incierto, diseña una forma de consultar, conciliar o compensar la operación. La cancelación real depende de las capacidades del sistema remoto y del tipo de trabajo; debe verificarse, no suponerse.
Trata el resultado desconocido como un estado propio
Cuando vence el plazo sin respuesta, el resultado puede ser «desconocido»: no sabes si el proveedor recibió la solicitud, si la ejecutó o si falló antes. Separar ese estado de «fallido» y «completado» ayuda a evitar decisiones peligrosas, especialmente en pagos, reservas, envíos o cambios de cuenta.
Antes de reintentar una acción con efectos, verifica si el contrato de la integración admite una clave de idempotencia o un mecanismo de consulta por identificador. La idempotencia puede evitar que una repetición produzca dos efectos, pero solo si está implementada y garantizada para esa operación. Si no existe esa protección, consulta el estado o deriva el caso a una revisión controlada antes de repetir.
Los reintentos también consumen tiempo. Inclúyelos dentro del límite total y evita que cada intento abra una espera completa e independiente. Un reintento sin presupuesto, con pausas mal ajustadas o multiplicado por varios componentes puede elevar la carga justo cuando el servicio está degradado. Para tareas que no necesitan respuesta inmediata, una cola y un flujo de seguimiento pueden ser más adecuados que mantener una conexión abierta.
Comunica el estado y ofrece una recuperación clara
El mensaje debe corresponder al nivel de certeza disponible. Si la operación sigue en curso, informa que está pendiente; si no se conoce el resultado, no la presentes como fallida ni como exitosa. Indica qué puede hacer la persona: esperar, volver a consultar o contactar con soporte. Evita pedir que repita una acción de consecuencias importantes sin advertir del riesgo de duplicación.
Los equipos internos necesitan el mismo contexto. Registra identificadores de correlación, dependencia, duración, etapa del timeout y resultado observado. Distingue los vencimientos de conexión de los de respuesta o del deadline total. No incluyas datos sensibles en registros innecesarios. Con esta información, soporte puede investigar un caso y tecnología puede localizar qué tramo consume el presupuesto.
Prueba y revisa los límites con señales operativas
Un límite no queda validado solo porque la integración funciona en condiciones normales. Prueba respuestas lentas, conexiones interrumpidas, cancelaciones, errores intermitentes y respuestas que llegan después del vencimiento. Comprueba tanto la experiencia de usuario como los efectos en el proveedor y el estado final registrado por tu sistema.
Observa la distribución de latencias, la frecuencia de timeouts, las operaciones pendientes y desconocidas, los reintentos y las incidencias por dependencia. Un aumento de vencimientos puede señalar un límite demasiado estricto, pero también una degradación real del proveedor, saturación local o una ruta de red problemática. No eleves el timeout automáticamente: primero identifica dónde se origina la demora y qué procesos quedan expuestos.
Documenta para cada integración el plazo por etapa, el presupuesto total, la acción al vencerlo, la política de reintentos y el mecanismo de recuperación. Revisa estos acuerdos cuando cambie el flujo de negocio o la latencia observada. El buen timeout no es el más largo ni el más corto: es el que protege el proceso, deja claro el estado y permite recuperarse sin efectos duplicados.