Idempotency

Make create operations safe to retry with a unique key, so a lost response doesn't produce duplicate requests.

Why idempotency matters

Create operations change state. If a create request succeeds but the response is lost, for example due to a network timeout, you don't want to create a second, duplicate request by retrying. An idempotency key lets you retry safely: the same logical operation with the same key doesn't create a duplicate.

Using an idempotency key

Documented POST requests use the Idempotency-Key header:

Idempotency-Key: <UNIQUE_KEY>

Key rules

• Use a unique key per logical create operation, for example a UUID generated when the operation starts.
• Reuse the same key when retrying the same operation after a lost or failed response.
• Do not reuse a key for a different operation.

Retrying a create

1. Generate the key

   Create a UUID at the start of the operation and keep it for the retry.

2. Send with the key

   Include it in the Idempotency-Key header of the create request.

3. Retry with the same key

   If the response is lost, send the identical request with the same key rather than a fresh one.

Related