Skip to content

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 POST request needs an Idempotency-Key header; without it you get 400 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: true header. 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.