Versions And Retries

ETags And If-Match

Every itinerary has a version. Reading one returns it in the ETag header. Every write to an existing itinerary must send it back:

PATCH /v1/itinerary/9b1c…
If-Match: "v42"
Content-Type: application/json

{ "title": "Five Days In Lisbon" }

• No If-Match → 428 preconditionRequired.
• An out-of-date ETag → 409 itineraryModified. Read the itinerary again, reapply your change and retry.

The response to a successful write carries the new ETag.

Idempotency-Key

POST /v1/itinerary, PATCH /v1/itinerary/{id} and the import routes accept an Idempotency-Key header. Send a new UUID per logical action and reuse it when you retry that action. A retry with the same key and body replays the first response; the same key with a different body returns 422 idempotencyKeyReused.

Duplicates

Creating an itinerary for the same destination and start date as one the traveller already has returns 409 duplicateItinerary with the existing itineraryId. Update that one, or pass allowDuplicate=true.

Paging

Lists return data and nextCursor. Pass cursor back to get the next page; stop when nextCursor is null. Cursors are opaque, so don't build your own.