ASP.NET Core Idempotency Keys and Retry Storms

Updated 8 November 2026 · Standard formula, shown below

Idempotency keys help an ASP.NET Core API make retried requests safe: if a client repeats an operation after a timeout, the server can recognize the same attempt and avoid performing its effect twice. They are especially useful for operations such as creating a payment, order, or booking, where network failures and automatic retries can turn uncertainty into duplicate work.

Why retries can become a storm

HTTP requests can fail in ways that leave both sides uncertain. A client may send a request, the server may commit the change, and the response may be lost before the client receives it. From the client’s perspective, a timeout does not reveal whether the operation happened. Retrying is a sensible way to recover availability, but blindly repeating a non-idempotent operation can create another effect.

A retry storm is a burst of repeated requests that increases load while a service is already struggling. It can begin when clients, gateways, or background workers retry after timeouts or transient errors. If each retry triggers the original work again, duplicate database writes or downstream calls add pressure, causing more delays and more retries. Retries are not inherently harmful; uncontrolled retries, synchronized retry schedules, and operations without duplicate protection are the dangerous combination.

For example, a mobile app submits an order. The API stores it but its response times out. The app submits again, and the API creates a second order. An idempotency key gives the server a way to connect both submissions to the same intended operation.

What an idempotency key does

An idempotency key is a client-generated identifier, commonly sent in a request header, that labels one logical operation. The client creates a fresh key for a new operation and reuses that key when retrying that operation. The API stores the key alongside the outcome, so a repeat can return the original result rather than execute the operation again.

The term “idempotent” has a precise meaning: repeating an operation has the same effect as performing it once. HTTP defines methods such as GET and PUT as idempotent in their intended semantics, while POST is not generally idempotent. An API can make a particular POST workflow safe to retry by implementing key-based deduplication. The key itself does not make a request safe; the server’s storage and handling rules do.

How to implement it in ASP.NET Core

There is no built-in ASP.NET Core feature that automatically makes arbitrary endpoint actions idempotent. A typical implementation uses middleware, an endpoint filter, or application-service logic to validate the key and coordinate a durable record. The storage and transaction design matter more than whether the check sits in middleware.

Require a key for selected operations. Accept it in a documented header, such as Idempotency-Key. Validate its presence, format, and maximum length. Do not require it indiscriminately for read-only operations.
Scope the key. Store it with the authenticated user or tenant and the operation or route. A key from one customer should not collide with another customer’s key or expose another customer’s response.
Record request identity. Associate the key with a fingerprint of the relevant request data. If a client reuses a key with a different payload, reject the request rather than silently returning an unrelated result.
Coordinate concurrent requests. Two copies may arrive at almost the same time. Use a database uniqueness constraint or another atomic claim mechanism so only one request can begin the operation. A “check, then insert” sequence without concurrency protection can let both through.
Persist the outcome and replay it. Store enough information to return a consistent result, such as the status code and response body, subject to your API’s security and data-retention rules. Define how in-progress requests are handled if another retry arrives before completion.

For database-backed work, put the idempotency record and business change in a transaction where feasible. That helps avoid the gap in which an order is committed but its key record is not, or vice versa. External side effects—such as a call to another service—cannot usually be made atomic with a local database transaction. Those workflows need additional coordination, such as an outbox and idempotent downstream processing, rather than assuming one transaction covers the entire system.

Choosing key scope and retention

Keys should be unique enough for the intended scope, but they should not contain secrets or personal data. Random identifiers generated by the client are a common choice. The API should treat them as opaque values and avoid logging them in places where logs are broadly accessible.

Retention must cover the realistic retry window, including delayed client retries and operational recovery. Keep records too briefly and a late retry may repeat the effect; keep every full response forever and storage grows without bound. Set a documented expiration policy based on the operation and business requirements. After expiry, the API may no longer be able to promise deduplication for that key.

Also decide what counts as the same request. Include relevant parameters and body data in the fingerprint, but exclude irrelevant transport details such as changing trace identifiers. Be explicit about behavior for a matching key with a mismatched payload, an operation still in progress, and a completed operation.

Retries, status codes, and common mistakes

Idempotency keys complement retry policy; they do not replace it. Clients should use bounded retries, a sensible timeout, exponential backoff, and jitter where appropriate. Backoff spreads retries over time, while jitter helps avoid many clients retrying in sync. Clients should distinguish retryable failures from validation errors and should preserve the same key for every retry of one logical operation.

Generating a new key on every retry: this defeats deduplication because every attempt looks new.
Reusing a key for a new action: this can return the previous action’s result or trigger a payload-mismatch error. Create a new key for each distinct operation.
Keeping keys only in process memory: a restart or a second API instance can forget the record. Use shared, durable storage appropriate to the required reliability.
Assuming a cached response prevents every duplicate: concurrent requests and failures between database and external-service steps still require careful coordination.

A repeated request with a completed key often receives the original response, but exact status codes and behavior are an API contract choice, not a universal rule. Document them so clients know whether to wait, retry, or investigate.

When keys are worth the added complexity

Idempotency is most valuable when duplicate execution has meaningful consequences and clients may reasonably retry: payments, order creation, reservations, job submission, or account actions. It is less useful for operations whose repeated execution is harmless, or where a different design already provides a durable unique business identifier.

Keys add database reads and writes, retention requirements, concurrency handling, and more cases to test. They also cannot guarantee exactly-once execution across arbitrary networks and independent systems. A more accurate goal is to make retries produce one effective business outcome within a defined scope and time window. For some workflows, a unique order reference, conditional update, or naturally idempotent PUT operation may be simpler. Choose the mechanism that matches the operation’s semantics.

Frequently Asked Questions

Does ASP.NET Core support idempotency keys automatically?
No. ASP.NET Core provides the web framework, but your application must define key validation, persistence, concurrency behavior, and response replay, or use a library whose behavior you have reviewed.

Should every POST endpoint require an idempotency key?
No. Require one where duplicate execution can cause an unwanted effect and retries are expected. Read-only endpoints and operations designed to be safely repeatable may not need one.

What should a client do after a timeout?
Retry the same logical request with the same key, using bounded backoff. A timeout alone does not tell the client whether the server completed the operation.

What happens if the same key is sent with different data?
A robust API should detect the mismatch, usually by comparing a request fingerprint, and reject it clearly. Returning the old result without checking can hide a client bug.

Do idempotency keys prevent all duplicate processing?
No. They can prevent repeated effects within the system and scope where they are enforced. External services, concurrent work, expired records, and partial failures need their own safeguards.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.