Idempotency
Safe retries with the Idempotency-Key header.
Developer documentation
When the network drops you cannot know whether a POST request reached the server. The Idempotency-Key header lets you repeat the same request safely: a second request with the same key does not create a second record.
Rules
- Every
POSTrequest needs anIdempotency-Keyheader; without it you get400 idempotency_key_required. The value is between 1 and 255 characters; a UUID is recommended. - A request repeated with the same key and the same body returns the current state of the resource with the status code of the first request and the
Idempotent-Replayed: trueheader. The body of the first response is not stored (personal data is not kept a second time), only the ID of the created record is; an update made in between therefore shows in the repeated response. - The same key with a different body gets
422 idempotency_key_reused. - If the first request is still running, the second gets
409 idempotency_in_progress; wait a little and repeat with the same key. - The window is 24 hours; an older key counts as a new request.
- The key is bound to your API key: the same value from another API key is a different request. A rotated API key counts as the same family and sees an interrupted repeat.
- A validation error (
400) leaves no record: fix the request and send it with the same key.
PATCH
PATCH requests do not take an Idempotency-Key. The values sent are absolute: repeating the same request leaves the record in the same state and writes no second event or history row. PATCH has no precondition: of two concurrent updates the last one wins.
Example
Steps 6 and 7 of the Quick start send the same request twice with the same key and get the same ID.