Idempotency
Retry safely. A timeout is not a failure.
Send an Idempotency-Key on every request that creates
something. If a request times out you do not know whether it succeeded,
retrying with the same key returns the original result instead of creating a
second payment.
Idempotency-Key: order-1001| Situation | Result |
|---|---|
| Same key, same body | The original response, replayed |
| Same key, different body | 409 idempotency_key_reused |
| Same key while still processing | 409 request_in_progress, retry shortly |
Reusing a key with a different body is an error, not
a replay. It almost always means a bug on your side, and quietly
returning the old response would hide it.
Keys last 24 hours. Use something already unique to the operation, such as your order id works well.
Declines are cached too: a payment the bank refused replays as the same refusal rather than being attempted again. Server errors are not cached, so a 5xx can be retried.