La idempotencia en las APIs de reservas de viaje, explicada

Una operación es idempotente cuando ejecutarla dos veces tiene el mismo efecto que ejecutarla una. Para una lectura, eso es gratis. Para una reserva que mueve dinero y retiene inventario, hay que diseñarlo.

El problema del timeout

Su servidor envía una petición de reserva. La respuesta nunca llega: un proxy soltó la conexión, una red móvil parpadeó, un deploy rotó un pod. ¿Se hizo la reserva?

Sin idempotencia, ambas respuestas salen caras. Si reintenta y el primer intento tuvo éxito, su cliente tiene dos reservas y usted una conversación de reembolso. Si no reintenta y el primer intento falló, no vendió nada y el cliente se va.

Cómo lo resuelven las claves de idempotencia

Con una cabecera Idempotency-Key, el reintento es seguro:

1. Genera una clave única por intención de reserva y la envía con la petición.
2. Si el servidor nunca vio la clave, procesa la reserva con normalidad.
3. Si el servidor ya procesó esa clave, devuelve el resultado original en lugar de reservar de nuevo.
4. Si la misma clave llega con un cuerpo distinto, la API la rechaza con IDEMPOTENCY_CONFLICT, porque eso es un bug del lado del llamante que merece hacerse notar.

La regla para el llamante es corta: reintente con la misma clave y nunca reutilice una clave para otra intención.

Cómo lo implementa traveldistro

Cada endpoint de reserva en entradas, traslados, coches de alquiler y eSIM exige la cabecera Idempotency-Key. Una reserva fallida revierte a cero estado residual, y los conflictos devuelven un 409 legible por máquina. El comportamiento completo está documentado en el catálogo de errores y la página de fiabilidad.