Idempotency keys belong in the database, not the handler
A note on Implementing Stripe-like Idempotency Keys in Postgres by Brandur Leach, published on brandur.org.
Most writing about idempotency stops at the idea: store a key, return the earlier result. This one keeps going into the part that actually bites, which is what happens when the operation has more than one step and the process dies between them.
The useful frame is treating the request as a small state machine with its progress recorded in the database, so a retry can resume rather than restart. That distinction matters enormously once an operation spans a local write and a remote call: restarting means calling the provider twice, and resuming means you need to know exactly how far you got.
It is also honest about the costs. Recovery points, foreign state mutations and the bookkeeping around them are real complexity, and the piece does not pretend otherwise.
This is not something you need for a contact form. It is something you need the first time a customer is charged and the licence is not issued because the process died between the two, and you have no record of which half happened. Read it before you are in that position rather than during.
This is the thinking behind the payments edge cases that bite at 2am.