Build a booking
Idempotency
Networks fail halfway through bookings. An Idempotency-Key lets you retry without ever booking the same guest twice.
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:
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
| 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