- name
- idempotency-patterns
- description
- Use when making retried HTTP commands or message processing safe against duplicate effects, including database-backed request keys, payload conflicts and concurrent retries. Do not apply caching as a substitute for business idempotency.
Idempotency Patterns
Spring Boot 3 baseline
The examples use Java 17 and Jakarta APIs supported by this Boot version. Keep dependencies managed by the project's Boot BOM.
Define the contract
Identify the authenticated tenant/principal, operation, idempotency key, canonical request hash, retention window and replayable result. Scope uniqueness by principal/tenant and operation; a raw client key must never allow reading another user's result. Authenticate and authorize before both initial execution and replay. Bound key length and stored response size. Document what same-key/different-payload and still-in-progress requests return.
Database-local effects
For PostgreSQL, the schema and claim example uses a composite primary key and INSERT ON CONFLICT DO NOTHING RETURNING. In a single database transaction: claim the key, apply the business write, store the resulting status/body/selected headers, then commit. Roll back the claim with the business mutation on failure.
If the insert returns no row, load the existing result in a subsequent statement under READ COMMITTED, compare the canonical hash and replay only when it matches. A concurrent insert waits on the uniqueness constraint; bound lock waits and return a documented retryable outcome on timeout. With snapshot isolation, serialization failures require retrying the whole transaction. Do not catch a unique-constraint violation and continue in an already-aborted transaction.
A result row and business write must use the same transaction manager and database. Return the stored result rather than reconstructing it from mutable current entity state. Keep replay headers allowlisted; do not persist cookies, bearer tokens or hop-by-hop headers.
External effects and messages
A database transaction cannot atomically include an HTTP payment or email. Write an outbox record with the business mutation and let a retryable worker perform the external effect using the provider's idempotency support. Reconcile uncertain outcomes before retrying irreversible effects. For messages, record a unique consumer/event pair and apply the projection in one transaction; acknowledge only after commit. Retry failed transactions and route poison messages deliberately.
Define retention from the real client retry window. Deleting a key permits a later repeat to execute again; do not present TTL as an exactly-once guarantee. Protect stored responses as application data and delete them according to the project's retention policy.