Docs
Developers

API Guide: Versions, ETags And Retries

The API version, how ETag and If-Match stop lost updates, and how Idempotency-Key makes a retry safe.

Three things keep writes safe: the /v1 version in every address, the itinerary's version (its ETag), and an idempotency key on writes you might retry.

Steps

Stay on /v1. The version is in the address, and GET https://api.travelyfe.com/ answers { "name": "Travelyfe API", "version": "v1", ... }. Send Travelyfe-Itinerary-Shape: clean on every itinerary request; it is the shape these docs describe.

Read the ETag. Every itinerary has a version. Reading it returns the version as the ETag header, and list rows carry it as etag. Treat it as opaque: use it exactly as you received it.

Send it back as If-Match on every change to the itinerary or its days, stops, flights, hotels, packing items, expenses and images, and on delete.

PATCH /v1/itineraries/5b0e5c1a-8f4d-4a52-9d3a-1c2e7f6b9a10
If-Match: "aXRpbmVyYXJ5OjQy"
Content-Type: application/json

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

A successful write answers the new ETag. Use it for the next write.

Add an Idempotency-Key to POST /v1/itineraries and PATCH /v1/itineraries/{id}: a new UUID (a random unique identifier) for each action, the same one when you retry that action.

What You Get

  • A retry with the same key and the same body within 24 hours replays the first successful answer instead of repeating the write.
  • A stale write is refused instead of overwriting someone else's change.

If It Doesn't Work

  • 428 preconditionRequired: no If-Match, or a value the API did not give you.
  • 409 itineraryModified: the itinerary changed since you read it. The response carries the current ETag. Read it again, reapply your change and retry with the new ETag.
  • 422 idempotencyKeyReused: the key was used with a different body. Make a new key for a new action.
  • 409 duplicateItinerary on create: the traveller already has an itinerary for that destination and start date. details.itineraryId names it. Update that one, or add ?allowDuplicate=true.

Limits

  • Idempotency keys are remembered for 24 hours.
  • Only POST /v1/itineraries and PATCH /v1/itineraries/{id} take an Idempotency-Key.

API Guide: Page Through Results

How limit, cursor and nextCursor work for itinerary lists and Explore, with a loop that reads every page.

API Guide: Errors And Rate Limits

The error shape, every status and code, and the per-minute request limits with the headers that report them.

On this page

StepsWhat You GetIf It Doesn't WorkLimitsRelated