Documentation

Retrying safely

Idempotency keys, and what happens when you reuse one.

Every endpoint that creates something accepts an idempotency key:

POST /api/v1/credentials
Idempotency-Key: 7f3c1e2a-...

Retry with the same key and you get the original response back, with Idempotent-Replay: true. Nothing is created twice.

The body is fingerprinted too

Reusing a key with a different body is refused with IDEMPOTENCY_KEY_REUSED rather than replayed. Replaying would answer a question nobody asked: you would receive the result of the first request while believing you had made the second.

While the first one is still running

A retry that arrives before the original has finished gets IDEMPOTENT_REQUEST_IN_PROGRESS. That is a correct and retryable answer — wait and try again.

If the process handling the original dies, its claim is released after two minutes, and a retry after that is treated as a new request. The dead attempt never created anything, so the retry is not a reuse of the key.

The window

24 hours. After that a key is forgotten and may be used again.