Scenario: Several commerce teams own checkout entry points. Retries after network timeouts can create duplicate order or payment work, but each team has different clients, release cycles and storage boundaries.
Executive explanation
Frame the customer problem as duplicate actions and ambiguous recovery, not merely inconsistent APIs. The key constraint is independent deployment. Choose a versioned idempotency contract with staged adapters over a synchronized rewrite. Measure duplicate-work incidents, unresolved requests and adoption by traffic, while acknowledging added storage and operational cost.
Architecture explanation
Compare centralized deduplication, per-service keys and a shared library. Define an idempotency key, request fingerprint, owner of the durable result and explicit responses for in-progress, completed and conflicting retries. Protect atomic claim-and-record behavior, bound retention and make downstream side effects recoverable. Test concurrent duplicate requests, a crash after payment authorization and an old client sending no key.
Execution and influence
Start with two teams that have the highest duplicate cost, publish a compatibility contract and provide adapters plus observability. Let old and new clients coexist; gate enforcement only after traffic and error evidence support it. Resolve incentives by funding migration work and assigning failure ownership. Maintain rollback for the new enforcement path, a deprecation decision log and a named owner for future versions.
An inadequate defense
We mandated one shared service and migrated every team because standardization is simpler.
It skips alternatives, team constraints, partial failure, compatibility, evidence and who operates the new dependency.
Follow-up questions
- What if the result record commits but the response is lost?
- How do you prevent the key from being reused for a different payload?
- Which teams should not migrate first, and why?
- When would you stop or reverse the rollout?
- What did you personally decide, implement, influence and delegate?