How to Ensure API Idempotency: Prevent Duplicate Requests in Backend Systems

In daily development, some APIs require strict idempotency, such as adding/deducting points or handling payments/refunds; without it, financial loss or user complaints can occur. The following example shows how a timeout in the points service triggers Nginx retries, causing multiple calls and excess points.

Common scenarios that lead to repeated API execution include:

1. Repeated request submission

Users may click a button rapidly or launch malicious attacks, resulting in multiple identical requests reaching the backend.

2. Retry mechanisms in distributed environments

Timeout retries, message‑queue re‑delivery, or producers sending duplicate messages can cause the same API to be invoked multiple times.

2. Approaches to guarantee idempotency

Frontend control

Disable the submit button or redirect after submission to prevent duplicate clicks.

This mitigates accidental repeats but cannot stop intentional abuse.

Redis SETNX

Use the business‑unique identifier (e.g., order ID) as a key in Redis with SETNX and an expiration time; only the first successful set proceeds with the business logic.

Backend token issuance

Clients obtain a token (e.g., JWT) from the server, then include it in subsequent requests; the server validates the token and stores it as a unique key in the database (or Redis). Duplicate tokens trigger a “duplicate request” response.

Database unique index

Define a unique constraint on the business identifier (such as order number). Inserting succeeds for the first request; subsequent attempts fail with a unique‑key conflict, prompting a “do not repeat” message.

Redis counting

Record the unique identifier in Redis and increment a counter; a count greater than one indicates a duplicate request.

State machine

Model business processes as state transitions; only valid state changes are allowed, and attempts that violate the state flow are rejected. Example SQL updates the order status and checks the affected row count.

update order set status = x where statue = '待支付';

Summary:

Duplicate calls can originate from the frontend (multiple clicks or attacks) or the backend (retry mechanisms).

Idempotency can be achieved via deduplication tables, Redis SETNX, token validation, unique indexes, counting, or state machines.

Optimistic or pessimistic locking solves concurrency but does not guarantee idempotency.