---
title: "Idempotency"
description: "Retry booking requests safely with the Idempotency-Key header."
url: "https://portal.konghotels.cloud/guides/idempotency"
image: "https://portal.konghotels.cloud/_og/d/c_Ocean.takumi,title_Idempotency,description_Retry+booking+requests+safely+with+the+Idempotency-Key+header.,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwRTJBMUYifX19,p_Ii9ndWlkZXMvaWRlbXBvdGVuY3ki,s_xB5uo96OM8bYT-0C.png"
---

# Idempotency

Networks fail halfway through bookings. An Idempotency-Key lets you retry without ever booking the same guest twice.

## [When to send a key](#when-to-send-a-key)

`POST /reservations` **requires** an `Idempotency-Key` header. Without one, you get `400 idempotency-key-required`. Every other `POST` accepts a key too, and we recommend sending one.

Use a UUID v4, generated once per booking attempt and stored with your booking before you call us:

```bash
curl -X POST "https://api.konghotels.cloud/reservations" \
  -H "apikey: $KONG_HOTELS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4c1f6a52-2a8e-4f0e-9a0b-1f3d7c9e2b11" \
  -d @reservation.json
```

## [How retries behave](#how-retries-behave)

| You send                                              | You get                                                               |
| :---------------------------------------------------- | :-------------------------------------------------------------------- |
| A new key                                             | The request runs. The response is stored for 24 hours.                |
| The same key and the same body                        | The stored response, with Idempotent-Replayed: true.                  |
| The same key with a different body                    | 422 idempotency-key-reused                                            |
| The same key while the first request is still running | 409 idempotency-request-in-progress. Retry after Retry-After seconds. |

`5xx` responses are not stored, so you can safely retry them with the same key.

Rule of thumb

If you're not sure whether a booking went through, send the exact same request again with the same key. You'll either create the booking or get the original confirmation back, never a duplicate.