Idempotency

Being built

The public API serves reads today, so there is nothing to make idempotent yet and no endpoint accepts Idempotency-Key. The contract below ships with the write endpoints — it is here so you can design your retry handling now. The reference always shows what the API actually serves.

A network timeout does not tell you whether the request arrived. Retrying a plain create risks a second ticket, a second booking, a second message to a customer.

Every write operation therefore accepts an idempotency key:

POST /tickets
Authorization: Bearer tko_...
Idempotency-Key: 2b7c1f8a-...
Content-Type: application/json

Send the same key when you retry the same request. The first call does the work; a retry returns that first result instead of doing it again.

Reads need none

Reads are already idempotent. The header is accepted only where it means something.

Choosing a key

Use a UUID per logical operation — generated once, stored with your own record of the attempt, and reused across every retry of it.

Do not derive it from the payload alone: two genuinely separate bookings for the same customer at the same time are a real thing a person might want, and a content-derived key would silently collapse them into one.

What you get back

Situation	Response
First call	The normal 201, work done
Retry of the same request	The original response, replayed
Same key, different body	422 idempotency_key_reused
Retry while the first is still running	409 idempotency_in_progress — wait and retry

The mismatch case is a guard, not an inconvenience: reusing a key for different content usually means the key is derived from something too coarse, and without the check one of the two operations would vanish.

Keys are scoped to your organization and remembered for 24 hours. After that a repeat is treated as a new request.