A caller that retries a POST request, most commonly a payment provider or webhook sender retrying a callback it isn't sure went through, can end up running your endpoint's logic a second time: a second row inserted, a second email sent, a second charge recorded. Sending an Idempotency-Key header avoids that.
How it works
Send a unique Idempotency-Key header (any string the caller generates, a UUID is typical) on a POST request. If a request with that exact key already ran against this endpoint, the stored response from that first run is sent back immediately, byte for byte, including its status code, your endpoint's own logic never runs a second time. A request with a key that hasn't been seen before runs normally, and its response is then stored under that key for next time. This works automatically for every POST endpoint, there's nothing to turn on, a caller that never sends the header is entirely unaffected.
A replayed response carries an Idempotency-Replayed: true header, so you can tell the two cases apart if you need to.
How long a key is remembered
24 hours from the first request, the same window most payment providers use for their own retries. After that, the same key is treated as new again.
A known limitation
Two requests sent with the same key at genuinely the same instant can both miss the stored response and both run your endpoint's logic, there's no lock held between the two, only a response stored after the fact. In practice a real retry (the caller waiting for a timeout or an error before trying again) never overlaps like this, only two requests fired deliberately in parallel would.
Tip: This pairs well with "What happens when an endpoint fails partway through", between automatic rollback on failure and a replayed response on retry, a caller can safely retry a POST without worrying about double writes either way.