How to use a UUID as an idempotency key

Payment APIs, message queues, and distributed systems use idempotency keys to prevent duplicate operations when retries occur. The key must be unique per logical operation and stable across retries of the same operation. UUID v4 is the standard choice: it is random enough to be unique, has no semantic meaning that could change, and is supported by Stripe, Adyen, and most major APIs as the expected format. This guide shows how to generate and use a UUID idempotency key.

Step-by-step guide

1. Generate a UUID for the operation: Generate one UUID here before making the API call. Store it alongside the pending operation in your database or in-memory state. This UUID is the idempotency key — the same key must be sent on every retry of the same logical request.
2. Include it in the API request header: For Stripe: add the header Idempotency-Key: <uuid>. For other APIs, check the documentation — common header names are X-Idempotency-Key, X-Request-ID, or Idempotency-Key. Pass the same UUID on every retry.
3. Discard it after success: Once the operation succeeds (HTTP 200/201), the idempotency key has served its purpose. Generate a fresh UUID for the next distinct operation — never reuse a key across different logical operations.

Frequently asked questions

How long should I keep the idempotency key?

Keep it for at least as long as you might retry the operation — typically 24–72 hours. Most payment APIs retain idempotency keys for 24 hours on their side. After that window, sending the same key may be treated as a new request.

Can I use any random string as an idempotency key, or does it have to be a UUID?

Most APIs accept any unique string up to a length limit (typically 255 characters). UUID is the conventional choice because it is universally unique and the format is well understood. Avoid timestamps or sequential integers — they are not unique enough under concurrent retries.