Idempotency key
An idempotency key is a string you attach to a request so the server can tell a retry from a new request. A network timeout never says whether the work happened, so a client that retries without one can send the same email twice. With one, the second call gets the first call's answer back instead of sending anything.
At a glance
- Category
- API behaviour
- Travels in
- An Idempotency-Key header on the request
- Chosen by
- The client — a UUID, or a natural key from your own data
- Applies to
- Writes that would otherwise repeat, such as a send
- Bounded by
- A retention window, after which the key is forgotten
How it works
You generate a key that is unique to the operation you are attempting and send it as a header. The server records the key with the response it produced. If the same key arrives again with the same payload, the recorded response is replayed instead of the work being done a second time. If the same key arrives with a different payload, that is a bug on your side and the server says so rather than guessing which request you meant.
Why it matters
A timeout is genuinely ambiguous: the request may have been processed, the response may have been lost, or nothing may have happened at all. Without a key, a client has to choose between duplicating and dropping. With one, retrying is always safe, which means retries can be automatic. For email that difference is visible to customers, because a duplicated receipt or a second password reset is the kind of bug people complain about publicly.
Example
An order service sends a receipt with the order identifier as the idempotency key. The first attempt times out after the message has already been queued. The retry carries the same key, the server recognises it, and the original response is returned. The customer receives one receipt. A month later the same order identifier is reused by mistake for a different message, the payload does not match, and the request is refused instead of silently replaying.
Common mistakes
- 01Generating a fresh key on each retry, which makes the header decorative and every retry a new message.
- 02Reusing a key across genuinely different requests, which either replays the wrong response or fails the payload check.
- 03Assuming the key lasts forever, when it is kept for a bounded window and a much later retry is a new request.
- 04Applying a key to a request that was never ambiguous, which adds bookkeeping without removing any risk.
In Rasket
Send an Idempotency-Key header on a send and the same key with the same payload replays the original response for 24 hours. Idempotency
Related terms
Frequently asked questions
What makes a good idempotency key?
Something that identifies the attempt rather than the moment, such as a UUID generated before the first call or a natural identifier from your own data. A timestamp is a poor choice because a retry will produce a different one.
Do I need one on every request?
Only on writes that would cause harm if repeated. Reads are already safe to retry, and so is any operation that ends in the same state whether it runs once or twice.
What happens if I send a key with a different body?
The request is refused rather than processed, because the server cannot tell which of the two requests you intended. Treat that error as a bug in your retry logic.
Sources
- The Idempotency-Key HTTP Header Field — IETF HTTP API working group
Last updated 16 September 2026.
Start sending this morning
Verify a domain and send your first email in minutes.