Ensuring API Idempotency: Why It Matters and How to Implement It

What is API Idempotency?

Idempotency, originally a mathematical concept, means that making the same API request multiple times must result in the operation being performed only once. Without it, repeated calls (e.g., payment or order creation) can cause serious problems such as double charging.

Why do idempotency problems occur?

Various situations can lead to duplicate requests:

Network fluctuations causing retries

User accidentally or intentionally submitting multiple times

Retry mechanisms (Nginx, RPC, business layer)

Page refreshes

Browser back button resubmitting forms

Browser history resubmission

Repeated HTTP requests

Scheduled tasks running multiple times

Double‑clicking submit buttons

How to ensure API idempotency?

Key approaches include client‑side prevention and server‑side validation.

Allow button to be clicked only once – disable or show a loading state after submission to avoid duplicate records.

Token mechanism – generate a token when the page loads, include it in each request, and let the backend reject repeats based on the token.

Post/Redirect/Get pattern – after a form POST, redirect to another page to prevent resubmission on refresh or navigation.

Store a unique flag in session – generate a unique identifier, store it in the session, include it as a hidden field, and process the request only if the identifier matches the session value.

Unique database index – rely on unique constraints to reject duplicate inserts, preventing dirty data.

Optimistic lock – use a version field; update only if the version matches, then increment the version. Example:

update table set version = version + 1 where id = #{id} and version = #{version}

This ensures that the first request succeeds while subsequent identical requests fail due to version mismatch.

Select‑then‑insert/update/delete – query before performing the operation; suitable for non‑concurrent environments or with JVM locking.

Distributed lock – use external systems like Redis or Zookeeper to acquire a lock before modifying data, ensuring only one process handles the request at a time.

State‑machine idempotency – design business processes as finite state machines and ignore requests that would move an entity to a previous state.

Deduplication table – insert a record with a unique key (e.g., order number) into a dedicated table; if insertion fails, treat the request as duplicate.

Buffer queue – enqueue incoming requests for asynchronous processing, filtering out duplicates; improves throughput but adds latency.

Globally unique identifier – combine source information with a unique sequence number; the backend processes only the first occurrence and rejects or delays subsequent identical requests.