Idempotency
A network cut must never create two requests or send two e-mails. Send the same request again with the same Idempotency-Key: you get the same response.
Where the header is required
Idempotency-Key (8 to 64 characters, unique per operation) is required on:
POST /requests,PATCH /requests/{request_id},DELETE /requests/{request_id},POST /requests/{request_id}/confirmation;POST /agent/conversationsandPOST /agent/conversations/{conversation_id}/messages;POST /webhook-endpoints.
Reads and POST /trade-matches (read-only) do not need it.
Replay
| Situation | Response |
|---|---|
| Same key, same body, within 24 hours | the original response, with Idempotent-Replayed: true |
| Same key, different body | 422 idempotency_key_reused |
| Same key, original request still running | 409 idempotency_in_progress: retry after a few seconds |
The key is tied to your account and to the mode (test or live): two partners cannot interfere.
Choosing keys
Derive the key from your own operation identifier: resa-0042-draft-1 for the draft of booking 0042, resa-0042-confirmation-1 for its confirmation. To deliberately redo an operation, change the suffix.
Content duplicates
Regardless of the header, an identical request already pending for the same person is not created again and triggers no new e-mail (duplicate_request, errors).