Making retries safe.
WHAT THE PROBLEM IS
A caller sends a request, the connection fails, and they do not know whether it succeeded.
WHAT THEY WILL DO
Retry.
WHAT THAT RISKS
A duplicate order, payment or record.
WHAT IDEMPOTENCY MEANS
Repeating the request produces the same result as sending it once.
WHICH OPERATIONS ARE NATURALLY IDEMPOTENT
Reads Replacing a resource entirely Deleting
WHICH ARE NOT
Creating Anything incrementing or appending
WHAT AN IDEMPOTENCY KEY IS
A unique value the caller supplies with a request.
HOW THE SERVER USES IT
Records it with the result Returns the stored result if the same key arrives again
WHY THAT WORKS
The second attempt gets the first outcome rather than a second effect.
HOW LONG TO RETAIN KEYS
Long enough to cover any plausible retry.
WHAT TO DO ABOUT A KEY REUSED WITH DIFFERENT CONTENT
Reject it, as a conflict.
WHY
It indicates a caller defect, and silently accepting it hides the fault.
WHERE THIS MATTERS MOST
Payments Order creation Anything with financial effect
WHAT TO DOCUMENT
That the key is supported, and how long it is honoured.
WHAT CALLERS SHOULD DO
Generate one per logical operation, not per attempt.
