Idempotent Request

Overview

What does Idempotent Request mean?

An Idempotent Request is a request that can be retried without creating an additional logical operation or unintended side effect.

How it works in practice

An idempotent request can be repeated without changing the intended result after its first successful execution. HTTP GET and PUT have defined idempotent semantics in the protocol, but POST may also be made idempotent through a server-side key and durable operation state. Payment APIs must account for side effects beyond the immediate response, including wallet broadcasts, ledger postings and notifications. The server should replay the original result or clearly report that the operation remains in progress while preserving its identity.

Limits and common misunderstandings

Two equal requests can be different business actions if the sender intends two purchases; blindly deduplicating by amount causes undercharging. Conversely, a retried POST without a stable key can generate duplicate payouts.

Additional implementation considerations

Implementers should decide whether the same idempotency key remains valid after a process restart, regional failover or API version change. The deduplication record and financial state transition must survive those boundaries or a retry can issue another payout. A temporary 'still processing' response is safer than falsely reporting failure when the upstream transaction may already have been sent. Clients should not generate a new idempotency key merely because a request timed out.

Related glossary terms

Idempotency Header; Idempotency Record; Idempotent Processing