Idempotency in travel booking APIs, explained

An operation is idempotent when running it twice has the same effect as running it once. For a read, that is free. For a booking that moves money and reserves inventory, it has to be designed.

The timeout problem

Your server sends a booking request. The response never arrives: a proxy dropped the connection, a mobile network blinked, a deploy rotated a pod. Did the booking happen?

Without idempotency, both answers are expensive. If you retry and the first attempt succeeded, your customer has two bookings and you have a refund conversation. If you do not retry and the first attempt failed, you sold nothing and the customer walks.

How idempotency keys solve it

With an Idempotency-Key header, the retry is safe:

1. You generate a unique key per booking intent and send it with the request.
2. If the server never saw the key, it processes the booking normally.
3. If the server already processed that key, it returns the original result instead of booking again.
4. If the same key arrives with a different request body, the API rejects it with IDEMPOTENCY_CONFLICT, because that is a bug on the caller's side worth surfacing loudly.

The rule for callers is short: retry with the same key, never reuse a key for a different intent.

How traveldistro implements it

Every booking endpoint across tickets, transfers, rental cars and eSIM requires the Idempotency-Key header. A failed booking rolls back to zero residual state, and conflicts return a machine-readable 409. The full behaviour is documented in the error catalogue and the reliability page.