Idempotency

An operation is idempotent when doing it twice has the same effect as doing it once. In distributed systems duplicates are normal, not rare:

• A client times out and retries a POST /payments that actually succeeded.
• Resilience4j Retry or the gateway retries a call after a slow response.
• Kafka redelivers a message when a consumer crashes before committing its offset (at-least-once).
• The outbox relay re-sends a row after a crash.
• A user double-taps the "Pay ₹2,998" button on a slow 3G connection.

@Entity
@Table(name = "idempotency_record",
       uniqueConstraints = @UniqueConstraint(columnNames = "idempotency_key"))
public class IdempotencyRecord {
    @Id @GeneratedValue private Long id;
    @Column(name = "idempotency_key", nullable = false) private String key;
    private String requestHash;          // SHA-256 of the request body
    private int responseStatus;
    @Lob private String responseBody;
    private Instant createdAt;           // purge after 24 hours
    // constructor, getters
}

@RestController
@RequestMapping("/api/payments")
@RequiredArgsConstructor
public class PaymentController {
    private final IdempotencyRecordRepository records;
    private final PaymentService payments;
    private final ObjectMapper json;

    @PostMapping
    @Transactional
    public ResponseEntity<String> pay(@RequestHeader("Idempotency-Key") String key,
                                      @Valid @RequestBody PaymentRequest req) throws Exception {
        String hash = Hashing.sha256(json.writeValueAsString(req));
        Optional<IdempotencyRecord> existing = records.findByKey(key);
        if (existing.isPresent()) {
            IdempotencyRecord r = existing.get();
            if (!r.getRequestHash().equals(hash)) {
                return ResponseEntity.unprocessableEntity().body("{\"error\":\"key reused with a different body\"}");
            }
            return ResponseEntity.status(r.getResponseStatus()).header("Idempotent-Replayed", "true").body(r.getResponseBody());
        }
        PaymentResponse result = payments.charge(req);   // calls Razorpay with the same key
        String body = json.writeValueAsString(result);
        records.save(new IdempotencyRecord(key, hash, 201, body));   // unique constraint stops a parallel duplicate
        return ResponseEntity.status(201).body(body);
    }
}

curl -X POST localhost:8084/api/payments \
  -H "Idempotency-Key: 7f3c9a2e-order-1001" -H "Content-Type: application/json" \
  -d '{"orderId": 1001, "amount": 2998.00, "method": "UPI"}'

# same command again (client retry)

HTTP/1.1 201 Created
{"paymentId":"pay_NqX81kLm2","orderId":1001,"amount":2998.00,"status":"CAPTURED"}

HTTP/1.1 201 Created
Idempotent-Replayed: true
{"paymentId":"pay_NqX81kLm2","orderId":1001,"amount":2998.00,"status":"CAPTURED"}

For events, use the event ID as the key: record every processed event ID in the same transaction as the business change, and skip IDs you have already seen.

@KafkaListener(topics = "order-events", groupId = "inventory-service")
@Transactional
public void onOrderPlaced(OrderPlaced event) {
    if (processedEvents.existsById(event.eventId())) {
        log.info("Duplicate event {} ignored", event.eventId());
        return;
    }
    inventoryService.reserve(event.orderId(), event.items());
    processedEvents.save(new ProcessedEvent(event.eventId(), Instant.now()));  // PK = eventId
}