Retries and idempotency

A request can time out after the API has done its work. Before sending one again, know what a second copy does.

Request	Sent twice
Any GET	Safe: reading changes nothing.
POST /v1/public/quotes	Safe: a quote books nothing.
POST /v1/public/checkout	Safe: the same hold with the same lead email books once. The second answer is the same booking, with booking_token and contact_token null. An on-request checkout with no hold needs an Idempotency-Key.
POST /v1/public/bookings/{ref}/cancel	Safe to detect: the second is 409 Conflict. Read the booking to see it is cancelled.
POST /v1/public/bookings/{ref}/contact-changes/{id}/confirm	Safe: a used code again changes nothing.
POST /v1/public/holds	Safe with an Idempotency-Key; without one, a second hold holds the places again.
POST /v1/public/enquiries	Not safe: the seller may get the message twice.

The Idempotency-Key header

POST /v1/public/holds and POST /v1/public/checkout take an optional Idempotency-Key header: any string of 1 to 255 characters that your site makes, such as a UUID.

• The same key with the same request answers with what the first request made, as it stands now, instead of doing it again.
• The same key with a different request is 409 Conflict, and does nothing.
• Keys are kept per storefront, and holds and checkouts share them, so never reuse one key for both.
• A hold’s attribution is not compared: a repeat with other tags answers with the first hold and its tags.

Holds

Make a new key for each hold the traveller means to make, for example one per click of “Book”, and send it again only when you retry that same hold.

• Keep the hold’s ref in the traveller’s session and check it out, rather than holding again, while hold_expires_at hasn’t passed.
• If a hold without a key timed out with no answer, holding again is safe for the traveller but holds the places twice until the lost one expires: 15 minutes for most trips, 30 for multi-day ones.
• GET /v1/public/holds/{ref} says how a hold stands, expired once its time is up.

Checkout

Because the same hold checks out once, retry a checkout after a timeout with exactly the same body. For an on-request option checked out with its selection and no hold, send an Idempotency-Key: a repeat answers with the booking the key first made. Keep the tokens from the first answer that reached you: a repeat carries none, and the traveller can still open the booking with the reference and their email.