Say it like this
- We should add an idempotency key to prevent duplicate charges.
- The API requires an idempotency key in the request header.
- Our payment gateway checks the idempotency key before processing the transaction.
Use it at work
Payments
- Send an idempotency key so retries don't charge twice.
- Each payment request needs a unique idempotency key.
Code review
- Can we add an idempotency key to this endpoint?
- We store idempotency keys for 24 hours.
Debugging
- The customer was charged twice because there was no idempotency key.
- The retry used a new idempotency key by mistake.
Don't say this
Idempotency keys prevent duplicate operations, not authentication. These are different concerns.
Practice
Try it
4 quick exercises
1. Your API needs protection against duplicate payments. How do you express this?
2. The client should _______ a unique _______ with every payment request.
3. Which sentence uses idempotency key incorrectly?
4. Rewrite this using idempotency key: 'We need to make sure that if someone sends the same payment request twice because the network was slow, they do not get charged twice.'
Say it out loud
Phrase 1 of 3
"We should add an idempotency key to prevent duplicate charges."
We don't save your recording. The word check uses your browser's speech recognition.
More about idempotency key
Real examples(3)
- in a standup
"We discovered a bug where customers were charged twice because we were not validating idempotency keys in our payment endpoint."
- in a code review
"Make sure to pass the idempotency key with every POST request to avoid creating duplicate database records on retry."
- in a team meeting
"Before we launch the new API, all mutation endpoints must support idempotency keys to handle network failures gracefully."
More mistakes(2)
Handle with care. Common mistake: confusing idempotency key with authentication tokens or session IDs. Idempotency keys specifically prevent duplicate operations, not authentication.
- ✕The server generates the idempotency key and sends it to the client.✓The client generates the idempotency key and sends it to the server in the request.
The client must generate the idempotency key so it can retry with the same key; the server only stores and validates it.
- ✕Idempotency keys are only needed for payments.✓Idempotency keys are useful for any operation that should not be duplicated: payments, creating records, sending notifications.
While common in payments, idempotency keys protect any mutation that could cause problems if executed twice.
Other forms(2)
- idempotency key noun
"The idempotency key ensures the request is processed only once."
- idempotency noun
"Idempotency is a critical property of safe APIs."
Often used with(5)
- generate an idempotency key · The client creates a unique identifier before sending a request
- pass / send an idempotency key · Include the key in the request headers or body
- validate / check an idempotency key · The server verifies the key and determines if the request is a retry
- idempotency key collision · When two different requests accidentally use the same key
- idempotency key header · HTTP header field containing the idempotency key (e.g., Idempotency-Key)
Similar words(3)
- request deduplication key · More descriptive but less commonly used; refers to the same concept
- idempotency token · Sometimes used interchangeably, though idempotency key is the standard term
- request ID · More general term; idempotency key is a specific type with deduplication logic
Opposites(2)
- duplicate operation
- non-idempotent request
Questions(5)
- What does idempotency key mean in software engineering?
- An idempotency key is a unique identifier that a client sends with a request to ensure that even if the request is retried multiple times, the server only executes the operation once. This is critical for preventing duplicate charges, duplicate database records, or duplicate notifications in systems where retries are common.
- How do you use idempotency key in a sentence at work?
- You might say: "We added idempotency key support to our checkout API" or "Make sure to include an idempotency key when calling this endpoint." In code review: "This endpoint is missing idempotency key validation—we should add it before launch."
- Who generates the idempotency key: the client or the server?
- The client generates the idempotency key (usually a UUID) and includes it in the request. The server receives it, checks if it has seen this key before, and either processes the request (if new) or returns the cached response (if a retry).
- Is idempotency key only for payments?
- No. While commonly used in payment systems, idempotency keys protect any operation that should not be duplicated: creating database records, sending emails, scheduling jobs, or any mutation where retries are possible but duplicates are harmful.
- Is idempotency key formal or informal?
- Idempotency key is a formal technical term used in documentation, code reviews, and technical discussions. It is appropriate for all professional contexts in tech companies.
