Idempotency Keys and Safe Retries

Server-side deduplication flow

First request with key idem-7f3a executes the transfer, persists ledger rows, and stores (key → response body hash, transferId, status) in Postgres. Retry with the same key and identical body returns the stored response without re-debiting. Same key with different amount or accounts returns 409 Conflict — the client reused a key incorrectly.

ShardPay processes idempotency check inside the same DB transaction as the ledger write when possible, so crash between transfer and store cannot create a committed transfer with no dedup record.

Walkthrough: mobile retry after 504

User submits $500 transfer; gateway times out after ledger commit but before response reaches phone. App retries with same Idempotency-Key. ShardPay's store hits on key, returns 201 with original transferId and body — user sees success, account debited once. Support logs show two HTTP requests, one ledger mutation.

Idempotency beyond HTTP

Kafka consumers at ShardPay dedupe by eventId header in a processed-events table — same semantics as HTTP keys. Database upserts use natural keys: UPDATE balance SET ... WHERE transfer_id = :id applied twice is safe when transfer_id is unique.

Idempotency is not automatic — INSERT without unique constraint duplicates rows. Every mutating code path needs an explicit key: HTTP header, event ID, or primary key constraint.

Walkthrough: concurrent duplicate requests

Two tabs submit the same transfer with identical idempotency key within 50ms. Both hit ShardPay; first transaction inserts idempotency claim and executes ledger. Second blocks on claim row lock, then reads completed response and returns without second debit. User sees one transfer in history.

// ShardPay idempotency store — transactional dedup (Java 17)
@Transactional
public TransferResult transfer(TransferRequest req, String idempotencyKey) {
    byte[] payloadHash = hash(canonicalJson(req));

    Optional<IdempotencyRecord> existing = store.find(idempotencyKey);
    if (existing.isPresent()) {
        IdempotencyRecord record = existing.get();
        if (!Arrays.equals(record.payloadHash(), payloadHash)) {
            throw new IdempotencyConflictException(idempotencyKey);
        }
        return record.response();
    }

    store.insertClaim(idempotencyKey, payloadHash); // unique constraint — second caller waits

    TransferResult result = ledger.execute(req);
    store.complete(idempotencyKey, result, payloadHash, Duration.ofHours(24));
    return result;
}

// Kafka consumer — same pattern with eventId
public void onSettlementEvent(ConsumerRecord<String, SettlementEvent> record) {
    String eventId = header(record, "eventId");
    if (processedEvents.markIfAbsent(eventId, Duration.ofDays(7))) {
        settlementService.apply(record.value());
    }
}

Designing keys with retries and sagas

Saga compensating steps need their own idempotency keys per step — not the same key as the forward transfer. ShardPay uses idem-{clientRequestId}-capture and idem-{clientRequestId}-refund so partial saga retries do not collide.

Keys should be generated once per user intent at the client, not per HTTP attempt. Retries reuse; new user taps "pay again" get a new key.