An idempotency key is a client-supplied identifier that lets an API detect duplicate requests and apply an operation’s server-side state change only once. It is required when a non-idempotent operation must safely tolerate retries. section 5.2.5
Review an API operation by asking:
- Does the operation become idempotent naturally? GET, PUT, and DELETE are naturally idempotent. section 5.2.5
- Does a POST or PATCH operation require retry-safe behavior? If so, add an idempotency key so duplicate requests can be detected and handled. section 5.2.5
Payment operation
A payment endpoint using POST is not naturally idempotent. If the client retries the same request, an idempotency key enables the API to recognize the duplicate and prevent the server-side payment state change from occurring twice. section 5.2.5
