​
Idempotency

Every POST endpoint that has side effects accepts an Idempotency-Key header. Replays with the same key and the same payload return the original response without re-running the side effect.

​
How it works

  1. Generate a UUID v4 client-side. Use it once.
  2. Send it in the Idempotency-Key header: 
    Idempotency-Key: f0e9b87c-3b6a-4f9e-9d7a-1234567890ab
  3. The server stores the request payload hash + the eventual response in Redis with a 24-hour TTL keyed by the idempotency key.
  4. Subsequent identical requests return the stored response.
  5. A request with the SAME key but a DIFFERENT payload returns 409 IDEMPOTENCY_KEY_REUSED.

​
Which endpoints support it

Any endpoint whose reference page lists Idempotency-Key in the headers table. As a rule of thumb: anything that creates a resource (POST), charges money, sends an email, or fires a notification.

​
Client recommendations

  • Use a fresh UUID per logical action — never reuse one across actions.
  • Retry on 5xx and network errors with the same key; the server will dedupe.
  • Treat 409 IDEMPOTENCY_KEY_REUSED as a programming bug, not a user-facing error.