Why it matters
Networks time out after the server did the work. The client retries. Without idempotency you get double charges, duplicate entries, and the same item added twice to a release. Message brokers deliver at least once, so every consumer has to cope with duplicates.
Techniques
| Technique | Use for |
|---|---|
Natural idempotency — PUT full state, DELETE, "set X = 5" | Most updates; prefer these designs |
| Idempotency key — client-generated key, server stores the result | Creates and payments; any non-idempotent POST |
Unique constraints / upserts — on business keys (releaseId + entryId + locale) | Adding items to collections |
Dedupe table — processed eventIds with a TTL | Message consumers |
Version / ETag checks — If-Match | Preventing lost updates |
For release items, adding the same (entry, version, locale) twice has to be a no-op, not a duplicate row. Bulk add was designed to skip invalid or duplicate items and add the rest, while the synchronous add API fails all-or-none and names the offending locale or entry. Two endpoints, two consciously different semantics, both safe to retry.
Checklist
- Is every
POSTeither naturally idempotent or keyed? - Do consumers dedupe on event ID?
- Does a retry return the same response, not a 409 that confuses clients?
- Are keys scoped per tenant and given a TTL?
Sources & further learning
Videos, courses, docs and books I recommend for this topic.
Related topics
Circuit Breaker, Retry, Timeout & Bulkhead
The resilience toolkit — fail fast, retry safely, bound waiting, and isolate resources so one slow dependency can't take down the whole system.
Transactional Outbox
Write the business change and the outgoing event in the same local transaction, then relay the event to the broker — no more "saved to DB but message lost".
Saga Pattern
Keep data consistent across services without distributed transactions — a sequence of local transactions, each with a compensating action if a later step fails.
API Evolution & Backward Compatibility
Change APIs without breaking clients — additive changes, tolerant readers, versioning strategy and explicit compatibility boundaries.