How would you design a POST endpoint so client retries do not create duplicate orders, payments, or records?

In production I make the idempotency boundary match the irreversible effect. If the operation only writes one database, the key record and business change commit in one transaction. If it calls a payment provider, I reuse a provider idempotency key, store the provider reference, and reconcile an ambiguous timeout before allowing another side effect. A local completed record cannot prove an external call succeeded unless the provider outcome is also known. I define what response is replayed, including Location and stable identifiers, while avoiding cached user-specific secrets. Key scope includes tenant or account and endpoint semantics; entropy and rate limits prevent key guessing from becoming an abuse path. Metrics show first attempts, in-progress collisions, completed replays, payload mismatches, ambiguous outcomes, and storage age. Tests send the same request concurrently, crash after the side effect but before the response, reuse a key with changed input, and retry after a timeout. That proves one durable business outcome rather than merely one controller execution.