Why every booking endpoint needs an idempotency key

A booking request can time out after the supplier has already confirmed it. If your client simply retries, you can end up with two PNRs and two charges. Idempotency keys solve this.

How it works

1. Your client generates a UUID for each logical operation and sends it as the Idempotency-Key header.
2. The gateway stores the key with a hash of the request body before calling the supplier.
3. If the same key arrives again, the stored result is returned. The supplier is not called a second time.
4. Reusing a key with a different body is rejected with 422, so mistakes are caught early.

Billing follows the same rule

Usage and booking fees are recorded against the idempotency key, so duplicate supplier callbacks and client retries can never create a second charge.

const key = crypto.randomUUID();

await withRetry(() =>
  fetch(`${BASE_URL}/flights/bookings`, {
    method: "POST",
    headers: { "X-Api-Key": apiKey, "X-Api-Secret": apiSecret, "Idempotency-Key": key },
    body: JSON.stringify(order),
  }),
);