Step 1 · The pattern
One tap, one charge
A shopper taps Pay. The app calls the payments API, the API charges the card, and a success response comes back. One order, one charge.
- payment request
- success
In short
Idempotency keys: how it works and how it breaks
Networks lose responses. When a payment request times out, the client cannot tell whether the charge happened, so the only sensible move is to retry. If the server treats that retry as a new request, the customer pays twice. An idempotency key fixes this. The client generates a unique key for each intended payment and sends it with every attempt. The server stores the key together with the result, in the same transaction as the charge. When a retry arrives with a key it has seen, the server skips the work and returns the stored result. Details matter: the key must be created by the client before the first attempt, the same key with different parameters should be rejected, and keys can be expired after a day or so. With this in place, retrying is always safe, which is what makes automatic retries possible at all.
In Spring Boot
An idempotency key with a unique constraint
@Service
class PaymentService {
@Transactional
public Receipt charge(String key, ChargeRequest req) {
// idempotency_key has a unique constraint: a repeat fails here
keys.saveAndFlush(new IdempotencyKey(key));
return receipts.save(Receipt.of(key, req)); // same transaction
}
@Transactional(readOnly = true)
public Receipt receiptFor(String key) {
return receipts.findByKey(key).orElseThrow();
}
}
@PostMapping("/payments")
Receipt pay(@RequestHeader("Idempotency-Key") String key,
@RequestBody ChargeRequest req) {
try {
return service.charge(key, req);
} catch (DataIntegrityViolationException duplicate) {
return service.receiptFor(key); // the first attempt's result
}
}The key and the receipt are written in one transaction, so either both exist or neither does. A retry with the same key fails on the unique constraint, and the controller returns the stored receipt instead of charging again. The same check can live in a HandlerInterceptor; it is in the controller here to keep the example short.
Gotcha: Catch the exception outside the @Transactional method. DataIntegrityViolationException is a RuntimeException, so by default the transaction rolls back, and that transaction cannot be used to read the stored receipt. Use saveAndFlush, or the insert may not reach the database until commit.
Names checked against the official docs on 15 Nov 2026:
How this comes up in interviews
"A customer taps Pay, the request times out and the app retries. How do you make sure they are charged only once?"
Then they ask
- The retry arrives while the first attempt is still being processed. What does the server do?
- The same key arrives with a different amount. How should the API respond, and why?
- How long do you keep keys, and what goes wrong if you expire them too early?
A strong answer covers
- A timeout tells the client nothing about whether the charge happened, so it has to retry.
- The client creates one key per intended payment before the first attempt and sends it on every attempt.
- The server stores the key with the result in the same transaction as the charge.
- A retry with a known key gets the stored result and no work is repeated.
- The same key with different parameters is rejected, and keys can be expired after a day or so.
Points to cover, not a script. Say them in your own words and tie them to a system you have worked on.
On one page: the track cheat sheet.
Sources: Stripe API reference: idempotent requests ↗ · AWS Builders' Library: Making retries safe with idempotent APIs ↗ · IETF draft: The Idempotency-Key HTTP header field ↗ · Report a problem
Diagrams are our own simulations: the timings, rates and counts in them are illustrative, not measurements. Captions are original wording.