How to Prevent Duplicate API Requests in ASP.NET Core Using Idempotency Keys

Imagine a customer clicks the Pay button on your website. The request reaches your API, but the response takes too long. The customer clicks the button again, and your API processes the payment twice.

The same problem can happen when a mobile app retries a request after losing its internet connection or when a network timeout occurs after the server has already completed an operation.

These situations are common in real applications. The problem is that the client may not know whether the first request succeeded.

One way to handle this is to use an idempotency key. It helps your API recognize repeated requests and avoid performing the same operation more than once.

In this article, you will learn what idempotency keys are, how to use them in ASP.NET Core, and how to store and validate them safely.

What Is an Idempotency Key?

An idempotency key is a unique value that identifies one operation requested by a client.

The client generates the key and sends it with the API request. The server stores the key along with the result of the operation.

If the client sends the same request again with the same key, the server checks whether that operation has already been processed. If it has, the server can return the saved result instead of performing the operation again.

For example, a payment request might look like this:

POST /api/payments
Idempotency-Key: 9f6a7c21-2d85-4d44-ae35-123456789abc
Content-Type: application/json

The request body might contain:

{
  "orderId": 105,
  "amount": 2500
}

The client should reuse the same key when retrying this particular payment request.

If the client starts a completely new payment operation, it should generate a new key.

The important rule is that the same operation must use the same idempotency key across retries.

Generating a new key for every retry defeats the purpose because the server will treat each request as a different operation.

Why Duplicate API Requests Are a Problem

Duplicate requests can cause different problems depending on what the API does.

For example:

• A payment API may charge a customer twice.

• An order API may create two orders for one purchase.

• A booking API may reserve the same seat more than once.

• An email API may send the same notification repeatedly.

• A wallet API may deduct money multiple times.

Not every repeated request is dangerous. Calling an API that returns product details multiple times is usually harmless.

However, requests that create records, move money, reserve resources, or trigger external actions need more careful handling.

Idempotency keys are especially useful for these operations because they let the server distinguish a retry from a new request.

How Idempotency Keys Work

The process is straightforward.

1. The client generates a unique key for an operation.

2. The client sends the key with the API request.

3. The server checks whether the key has already been used.

4. If the operation has completed, the server returns the previously stored result.

5. If the key is new, the server processes the operation and saves its result.

6. If the client retries the request, the server uses the stored result instead of repeating the operation.

A simple example makes this easier to understand.

Suppose a client submits a payment request with key payment-123.

The server processes the payment and stores the result. The response gets lost because of a network problem.

The client sends the same request again with payment-123. Instead of charging the customer again, the API returns the result saved during the first request.

The client receives the response it needs without creating another payment.

Step 1: Create a Table to Store Idempotency Keys

For a production API, idempotency records should be stored somewhere that survives application restarts.

An in-memory dictionary is not enough for most production systems. If the application restarts, the stored keys disappear. It also does not provide reliable coordination between multiple application instances.

A database table is a common choice.

For example, you can create an SQL Server table like this:

CREATE TABLE dbo.IdempotencyRequests
(
    Id BIGINT IDENTITY(1,1) PRIMARY KEY,
    IdempotencyKey NVARCHAR(100) NOT NULL,
    RequestHash VARCHAR(64) NOT NULL,
    Status NVARCHAR(20) NOT NULL,
    ResponseBody NVARCHAR(MAX) NULL,
    CreatedAtUtc DATETIME2 NOT NULL
        DEFAULT SYSUTCDATETIME(),
    CompletedAtUtc DATETIME2 NULL
);
CREATE UNIQUE INDEX UX_IdempotencyRequests_Key
ON dbo.IdempotencyRequests(IdempotencyKey);

Each record stores the key, a hash of the request, its processing status, and the response when the operation completes.

The unique index is particularly important. It prevents two concurrent requests from successfully creating separate records with the same key.

In a multi-user application, you may need to scope keys by customer or account. In that case, use a unique constraint on the appropriate combination, such as UserId and IdempotencyKey, rather than assuming every key is globally unique.

The table should also have a cleanup policy so old records do not remain forever. The retention period must be long enough to cover the retries your API promises to support.

Step 2: Require an Idempotency Key in ASP.NET Core

Your API should check that the client sends a valid key before processing an operation that requires idempotency.

For example, a controller action can read the key from the request headers:

using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/payments")]
public class PaymentsController : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> CreatePayment(
        [FromBody] CreatePaymentRequest request)
    {
        if (!Request.Headers.TryGetValue(
                "Idempotency-Key",
                out var key))
        {
            return BadRequest(new
            {
                message = "Idempotency-Key header is required."
            });
        }
        string idempotencyKey = key.ToString();
        if (string.IsNullOrWhiteSpace(idempotencyKey) ||
            idempotencyKey.Length > 100)
        {
            return BadRequest(new
            {
                message = "Invalid idempotency key."
            });
        }
        // Process the request through an
        // idempotency service.
        return Ok(new
        {
            message = "Request received."
        });
    }
}
public sealed record CreatePaymentRequest(
    int OrderId,
    decimal Amount);

This example validates the header but does not yet prevent duplicate payments. That requires storing and checking the key as part of the actual processing workflow.