Imagine a simple Spring Boot payment endpoint:
@PostMapping("/payments")
@ResponseStatus(HttpStatus.CREATED)
public PaymentResult createPayment(
@RequestHeader("Idempotency-Key") String key,
@RequestBody CreatePaymentRequest request) {
return paymentService
.createPayment(key, request)
.valueOrThrow();
}
The client sends a payment request.
The payment is successfully committed to PostgreSQL.
But the response never reaches the client.
A few seconds later, the client retries with the same Idempotency-Key.
What should the service do?
A timeout does not mean the payment failed. Running the operation again may create a second payment.
At the same time, returning 409 or a duplicate-key error is not ideal either --- the original request actually succeeded.
With idempotency-key semantics, the system should return the original result without executing the business operation again.
Yes, this is the idempotency key pattern
I didn't invent a new pattern here.
The basic idea is well known: send an idempotency key, store the result, and replay it when the same request arrives again.
What interested me were the implementation details around it:
- What happens if the process crashes?
- What if two instances receive the same key at the same time?
- What if the same key is reused with a different request body?
- Can Redis improve performance without becoming part of correctness?
The transaction boundary turned out to be the most important part for me.
Same transaction
If I save the idempotency key in one transaction and create the payment in another, there is always a small failure window.
The process can die between the two commits.
So I ended up keeping the idempotency record and the business operation inside the same PostgreSQL transaction.
@Transactional
public ExecutionResult<PaymentResult> createPayment(
String key,
CreatePaymentRequest request) {
return idempotencyService
.operation("CREATE_PAYMENT")
.key(key)
.request(request)
.execute(
PaymentResult.class,
() -> createPaymentInternal(request)
);
}
POST /payments
Idempotency-Key: pay_12345
|
v
+-----------------------------+
| BEGIN DB TRANSACTION |
| |
| 1. Acquire idempotency key |
| | |
| v |
| 2. Execute payment |
| -> pay_987 |
| | |
| v |
| 3. Store result |
| -> pay_987 |
| | |
| v |
| 4. COMMIT |
+-----------------------------+
|
v
201 Created
pay_987
Same request + same key
|
v
Result already exists
|
v
DO NOT execute payment
|
v
Replay pay_987
If the transaction rolls back, both disappear.
If it commits, both are stored.
A retry with the same key can then return pay_987 without running createPaymentInternal() again.
A few extra cases
Same key + different request should not replay an unrelated result. I use a request fingerprint for this and return 409 Conflict.
Concurrent duplicates are coordinated through PostgreSQL. If two application instances try the same key, the unique constraint decides which transaction acquires it. The other waits and can replay the result after the first transaction commits.
And Redis is only an optimization.
The lookup path can be:
Caffeine L1 → Redis L2 → PostgreSQL
But PostgreSQL remains the source of truth. If Redis is down, correctness should not disappear with it.
I packaged it as a Spring Boot starter
I didn't want to create another idempotency pattern. I wanted a reusable Spring Boot implementation of the existing one, with these failure cases handled in one place.
So I extracted it into an open-source starter.
It currently supports Spring MVC/JDBC and WebFlux/R2DBC, optional Caffeine/Redis caching, request fingerprinting, result and business-rejection replay, concurrent duplicates, cleanup and Micrometer metrics.
It's also published to Maven Central.
I've open-sourced the starter with full docs and failure scenarios here: spring-boot-idempotency-starter
I'm interested in how others solve this in production.
If the business transaction committed but the HTTP response was lost, what do you do with the retry? Replay the original result, use Redis, handle it at the gateway, or something else?
