Idempotency Keys: Safe Retries for Account and Payment APIs

Bind the key to one intended action

Create an internal operation record before attempting the external request. It should identify the target account, action, amount or other protected parameters, request version and stable retry key. Store the resulting provider reference and outcome against that record. A random key alone cannot explain what the operator intended.

Keep sensitive customer data out of the key itself. If a payload changes, determine whether that is a new approved operation or a correction that requires resolving the previous attempt first. Do not quietly mint a new key after a timeout: the original request may already have executed despite the missing response.

Read scope and retention as contract terms

Stripe documents reuse of an executed request's result, including a 500 response, and potential key pruning after at least 24 hours. Validation or pre-execution conflicts have different treatment. Adyen documents company-account scope, a current 7–14-day validity period and no deduplication across separate regional endpoints.

These differences are why a generic retry helper needs provider-specific settings and tests. A key used in one region, account or API might not protect an attempt sent elsewhere. Once retention is uncertain, inspect the operation and authoritative provider state instead of assuming that either the old key or a fresh key makes resubmission safe.

Test the crash and retry boundaries

Exercise failures before the provider accepts the request, after acceptance but before the response reaches you, and after the response arrives but before local persistence completes. The local recovery process should rediscover the same operation and reconcile its outcome, not start a second business action.

Idempotency also differs from event deduplication and database isolation. One protects repeated outbound requests under a provider contract, another handles repeated inbound events, and a third protects local concurrent updates. Design the interfaces between them. Stripe examples here explain engineering behavior only; its restricted-business policy remains separate and prohibits funded prop trading under the reviewed policy.

Example: a timeout with an unknown result

A fictional account-credit request uses operation OP-18 and key K-18 for 250 units. The response times out. A retry with the same key and unchanged payload follows the target API's contract. A request for 275 units is not the same retry and must not reuse the record silently. If the key may have expired, the operator first reconciles whether OP-18 executed, preserving that uncertainty until evidence resolves it.