Where Should API Idempotency Be Placed to Avoid Chaos in System Development?

API idempotency is not a standard requirement for all interfaces, but rather for write operations that may have side effects due to retries, timeouts, or duplicate submissions. In our 2026 project deliveries, we generally apply idempotency only to interfaces such as payment callbacks, order creation, and inventory deduction. Read-only queries are naturally idempotent and need no handling. When implementing, first determine whether it is needed, then choose whether to place it in the business layer or storage layer; otherwise, you risk missing the design or over-engineering.

What Problem Does API Idempotency Actually Solve?

API idempotency means that the impact of executing the same request once or multiple times on the system remains the same. Network jitter, RPC timeout retries, double-click submission on the frontend, and duplicate consumption from message queues can all cause the server to receive multiple requests with identical business semantics. Without idempotency, this may lead to duplicate orders, duplicate charges, or duplicate shipments.

In our project delivery practice, we review each write request during API reviews rather than troubleshooting through logs after launch. The three-step verification method below is designed to quickly filter out interfaces that must implement idempotency.

• Client timeout triggers a retry, sending the same request twice
• Automatic RPC framework retries, such as Feign retry or Nginx proxy_next_upstream
• Duplicate form submission, when the user clicks the Submit button multiple times
• Duplicate message queue consumption, when the offset is not committed after successful processing

Three-Step Verification: How to Decide Whether an Interface Needs Idempotency

The three-step verification is a common judgment method in projects. It checks in order to avoid deciding based on intuition. Each step has a concrete basis and is quick to execute.

1. Check whether the request changes system state. Read-only requests do not need it; create, update, and delete operations require further checking.
2. Check whether the request may be sent repeatedly. Anything going over external networks, with timeout retries, or with user interaction buttons may be duplicated.
3. Check whether repeated execution causes additional side effects. For example, duplicate charges, duplicate coupon issuance, or duplicate inventory movement require idempotency; if it only sets the same field repeatedly, the impact is minimal.

In practice, many teams skip ahead after only the first step, causing read-only interfaces to also have idempotency keys, unnecessarily increasing complexity. The third step is often underestimated; for example, an interface like update user notes yields the same result when repeated and does not actually need idempotency, while update user balance must have it.

Which Layer Is More Reliable for Idempotency: Comparison of Three Approaches

Based on implementation layers, there are three common approaches: frontend duplicate prevention, business logic layer idempotency, and database unique constraints. They are not mutually exclusive; rather, they offer increasing reliability and increasing implementation cost. Below we describe their applicable conditions based on common project practices in 2026.

• Frontend button graying/disable: Low implementation cost, only prevents accidental user clicks, cannot prevent network retries or request replay, and cannot serve as an independent guarantee.
• Business layer idempotency (unique request ID + state check): Relatively balanced. The client generates a globally unique ID and submits it with the request; the server first checks whether the ID has been processed, then executes the business logic, using a Redis lock to control concurrency. Suitable for most interfaces; be mindful of lock timeout and atomicity.
• Database unique constraint: Provides stronger fallback. For example, a unique key on order numbers or payment transaction IDs. However, it requires significant changes to sharded databases or existing table structures, resulting in higher cost.

Based on experience range, business layer idempotency can cover about 70% to 90% of simple scenarios, with database unique constraints added on top for critical financial operations. If both business layer handling and database constraints exist, ensure consistency in check-then-write; otherwise, concurrency may still break through.

Common Pitfalls in Implementation in 2026

At delivery sites, due to budget and scheduling constraints, some projects only implemented business layer checks without adding database unique constraints. As a result, duplicate orders still appeared under high concurrency, and they had to stop the service to add indexes, at a considerable cost. Therefore, the baseline for such scenarios is to at least add unique keys to financial and inventory interfaces.

In projects, clients often get stuck on the following types of issues, all of which can cause idempotency to fail or performance to degrade.

• The client generates a new request ID on every retry, so the server cannot recognize duplicate requests, leading to duplicate orders.
• Redis lock timeout is set too short, allowing concurrent requests to interleave into business code, defeating the lock.
• Idempotency state is kept only in memory and is lost after a service restart, requiring re-evaluation.
• The idempotency table and business table are not in the same transaction; after the check, the business operation fails, but the idempotency marker has already been written, causing the same request to be rejected.

To solve these pitfalls, first define the lifecycle of the request ID: the client generates it on the first request and reuses it on retries; the server uses a Redis lock plus a database unique constraint as dual protection; the idempotency record write must be in the same local transaction as the business operation, and cannot be committed separately.

What qualifies as acceptable? You can verify it like this: send the same request ID five times consecutively, and only one business record should be produced; if two different request IDs concurrently submit the same business data, they should be treated as different requests and allowed to be processed separately, but if there are business uniqueness requirements (such as the same order number), corresponding constraints should also exist.

What Are the Costs of Over-Engineering Idempotency?

Not all write interfaces need heavy artillery. If you add Redis locks and unique constraints to low-frequency management interfaces, the costs are obvious: one extra Redis query, potentially adding a few milliseconds to tens of milliseconds to response time; longer table lock time in transactions, reducing concurrent throughput; and you also need to maintain request ID generation and storage. Based on experience range, forcing idempotency on an ordinary write interface may add about half a day of development effort, while the maintenance cost persists.

• Low-frequency interfaces also introduce global request ID generation and storage, with benefits far outweighed by costs
• All write operations are wrapped with distributed locks, causing significantly increased latency for individual APIs
• Excessive transaction scope, locking unrelated updates in the same transaction, slowing overall performance

So the core question is whether it is worth it. For a simple update in an internal admin panel, where the API is called by a limited number of people and the repetition probability is very low, adding idempotency actually slows down operations. In such cases, using the database's built-in constraints or optimistic locking is enough; you don't need to dedicate a request ID.

A better approach is to grade the levels: no idempotency for read interfaces; only state de-duplication for ordinary write interfaces; and only strong-consistency interfaces such as finance and inventory need the combination of request ID + unique constraint.

Frequently Asked Questions

Below are several common follow-up questions when designing API idempotency.

Is idempotency the same as duplicate prevention?

No. Duplicate prevention usually means preventing the same request from being submitted repeatedly within a short period, while idempotency requires that any number of repeated executions produce the same result, making it stricter than duplicate prevention.

Do query interfaces need idempotency?

If they don't change state, no; but interfaces with write operations such as query-and-update status should be treated as write interfaces.

Is a unique request ID sufficient?

No. The request ID needs to be combined with server-side state checks or unique constraints; otherwise, concurrent requests arriving simultaneously may still execute repeatedly.

Can idempotency be implemented at the gateway layer?

The gateway layer can only perform coarse-grained deduplication and lacks business context, making misjudgment likely. It is recommended that the gateway only handle rate limiting, and idempotency should reside within business services.

Can idempotency be added after an API has been launched?

Yes. Common practices include adding a new idempotency table or adding a unique key to the business table, and cleaning up existing data. Note that during deployment, the constraint should be added before changing code; otherwise, there is a risk of duplicate data.

Applicable Scenarios and Boundaries

Idempotency design is suitable for strong-consistency scenarios such as payments, orders, inventory, and coupons, and also for external APIs to handle caller retries. It is not suitable for pure query interfaces, simple writes that are fully controllable between internal services, or single-machine business with no retry mechanism. Forcing idempotency in such cases will degrade performance.

• Suitable for: external APIs, payment callbacks, order submission, inventory deduction, and message duplicate consumption scenarios
• Not suitable for: pure query interfaces, simple writes with no retry mechanism in internal services, and single-machine scenarios without concurrency

Boundaries should be clear: do not apply idempotency to read-only APIs, and do not protect all APIs with transaction locks. Based on experience, first compile an API list, filter it using the three-step verification method, and then decide the implementation depth.

According to Xiyue Company's project delivery practice, first list all write interfaces and use the three-step verification to filter out the must-do list. During implementation, adopt a three-layer structure of client unique request ID + server-side state check + database unique constraint, but not every interface needs all three layers. Before launch, use scripts to simulate duplicate requests and concurrent requests for verification. The methods in this article apply to most business systems, but not to pure query scenarios or fully controlled single-machine environments.