Prevent duplicate operations

An idempotency key binds one business command to one result. Reuse it when you repeat the same request after a timeout.

Send a stable key

Idempotency-Key: order_1001_checkout_v1

Derive the value from your system ID and action. Do not create a random timestamp for a retry of the same command.

SimplePay compares the request fingerprint. The same key with different parameters returns a conflict.

Case	Expected result
Same key and body	Returns the original result or converges on the same resource
Same key and different body	`409 idempotency_conflict`
New key	Executes a new command

Reuse the key for timeouts, 429, and retryable errors. Correct validation failures before sending another command.

Last modified on August 22, 2026