Idempotency (Request Fingerprint Mode)

Making an endpoint idempotent simply means that it will return the exact same response (from a cache) for a particular "unique" request everytime until the cached response is purged from the cache. The first time a particular request comes in, the cache will be checked to see if that exact request has come in before. If the request is not an original request and there is a cached response for that exact request, the previously cached response is served without executing the endpoint handler for it. If it is an original request and there is no cached response, the endpoint handler is executed, the response is cached and returned to the client. Any subsequent/repeated requests consisting of the exact same set of parameters such as headers, route/query params, request body, will result in the cached response being served without executing the endpoint.

Server-Side Setup

To make endpoints idempotent, simply enable the idempotency middleware and configure idempotency for the endpoints like so:

Program.cs
var bld = WebApplication.CreateBuilder();
bld.Services
   .AddFastEndpoints()
   .AddIdempotency(); //add this

var app = bld.Build();
app.UseOutputCache() //add this before FE
   .UseFastEndpoints();
app.Run();
Endpoint.cs
sealed class MyEndpoint : EndpointWithoutRequest
{
    public override void Configure()
    {
        Get("my-endpoint");
        AllowAnonymous();
        Idempotency(); //add this
    }

    public override async Task HandleAsync(CancellationToken c)
    {
        await Send.OkAsync($"TimeStamp: {DateTime.Now.Ticks}");
    }
}

Client-Side Setup

The only special requirement for the client is to simply send in a header with the name Idempotency-Key (customizable), and a unique value per each request. There is no particular format requirement from the server, as long as the value is different per each unique request (user action). An example Curl request would look like this:

curl -X 'GET' \
  'http://localhost:5000/my-endpoint' \
  -H 'accept: text/plain' \
  -H 'idempotency-key: 1dc3d9a8527047069f8056175a71fe79'

Requests to idempotent endpoints cannot be made without the Idempotency-Key header. A 400 - Bad Request will be served if the header is missing from the request.

Request Uniqueness

The uniqueness of incoming requests to an endpoint is determined by generating a Cache-Key. By default, the following request parameters participate in the cache-key generation:

  • URL including scheme, host, port, path
  • Route parameters
  • Query parameters
  • Idempotency-Key header
  • A limited set of additional headers (customizable)
  • Form data including form fields, form file names & file sizes (actual file bytes are not considered)
  • Body content (be it JSON or anything else)

Multiple requests containing the exact same set of request parameter values will be identified as duplicates and only the first request will result in the endpoint handler being executed. The subsequent duplicate requests will receive the cached response generated by the initial request.

Performance Considerations

Idempotency should not be enabled for all endpoints of a system. It should be carefully chosen only for endpoints that actually require idempotency where there is a potential for trouble from duplicate requests for the same client/user action. Such as in payment processing where duplicate requests would result in duplicate charges to a customer.

The performance impact lies in the fact that each incoming request must be inspected by the middleware in order to generate the cache-key. The inspection of the request body stream causes the data to be buffered to memory/disk. Due to this reason, idempotent endpoints will never be as performant as regular endpoints. Performance is the price you pay for this safety feature.

If the requesting clients are under strict quality control and can be guaranteed that the same idempotency-key value will not be mistakenly re-used, you can mitigate most of this performance impact by making the request body content not participate in the cache-key generation. In which case, the uniqueness of the requests will be determined solely by the request URL, route/query params and header values. The body content will be ignored, and no content buffering will occur.

Customization Options

The following options can be customized per endpoint as well as globally with the use of an endpoint configurator.

Idempotency(
    o =>
    {
        //idempotency-key header name.
        o.HeaderName = "Idempotency-Key";

        //additional header names to be considered for cache-key generation.
        o.AdditionalHeaders.Add("My-Header");

        //controls whether body content participates in cache-key generation.
        o.IgnoreRequestBody = true;

        //the time limit to cache responses for.
        o.CacheDuration = TimeSpan.FromDays(1);

        //automatically adds the idempotency-key header to the response.
        o.AddHeaderToResponse = true;

        //text description for the swagger request header parameter.
        o.SwaggerHeaderDescription = "This is an idempotent endpoint.";

        //a function to generate example values for the swagger parameter.
        o.SwaggerExampleGenerator = () => Guid.NewGuid().ToString("N");

        //used to determine the format of the swagger parameter.
        o.SwaggerHeaderType = typeof(Guid);
    });

Distributed Cache Storage

The idempotency feature is implemented as a custom cache policy for the built-in output caching middleware. By default, the output caching middleware uses the in-memory cache storage provider. You can either plug in your own implementation of IOutputCacheStore or use the Microsoft provided Redis provider.


Financial Mode Idempotency (Stripe Style)

Consider a client submitting a payment request. The server processes the payment, but the connection drops before the client receives the response. The client retries, not knowing whether the payment went through. Without protection against duplicate execution, the customer could be charged twice.

Financial idempotency is designed for situations like this. Before running your endpoint, it reserves the request key for that caller. A retry can then receive the stored successful response without running the endpoint again. If the outcome of the first request is uncertain, the reservation is kept rather than allowing another attempt that might repeat the charge.

This is separate from the output caching based request fingerprinting approach described above. Use FinancialIdempotency() instead of Idempotency() on financial endpoints, not both together.

Enabling Financial Idempotency

First, register the services and add the middleware before UseFastEndpoints() like so:

Program.cs
bld.Services
   .AddFastEndpoints()
   .AddFinancialIdempotency(c =>
   {
       c.CallerScope = ctx => ctx.User.FindFirst("account_id")?.Value;
       c.DefaultDuration = TimeSpan.FromHours(24);
       c.DefaultUnreplayableRetention = TimeSpan.FromHours(24);
   });

app.UseFinancialIdempotency()
   .UseFastEndpoints();

The CallerScope identifies who the request belongs to. In this example, it comes from an account_id claim supplied by your authentication setup. Use a stable account or tenant identifier from validated authentication, not a raw bearer token or cookie. This keeps the same operation protected even when the caller refreshes their credentials.

A caller scope is required globally or per endpoint. If it is missing for a request, the request fails before a reservation is created. Supporting anonymous callers requires an explicit scope choice.

Then enable financial idempotency on the endpoint:

Endpoint.cs
public override void Configure()
{
    Post("/charges");
    FinancialIdempotency(o => o.ReplayStatusCode = 200);
}

The example configures stored responses to be replayed with a 200 status code.

Place routing, authentication, authorization and exception handling before the financial middleware. If you use response compression, place that before it too, so the middleware captures uncompressed content.

Sending And Retrying Requests

The client sends an Idempotency-Key header, just as in the client-side setup above. Generate a new key for each new operation and reuse that key when retrying the same operation. The header must contain a single, nonblank value of at most MaxKeyLength characters (256 by default).

For example, when a client retries a charge, the middleware handles it as follows:

Situation Result
The same key and payload were already processed successfully The stored response is returned without running binding, validation, processors or the handler again.
The first request is still running The retry receives 409 Conflict immediately with Retry-After: 1. Retry after the indicated delay.
The key is reused with a different payload The request receives 422 Unprocessable Entity. Retrying the same request will not succeed.
The earlier attempt cannot safely be replayed The retry receives 409 Conflict without Retry-After. Reconcile the outcome before retrying.

The payload comparison includes query values, body bytes, and uploaded file contents and metadata. Changing a query value therefore counts as changing the payload, not as starting a separate operation. Successful responses, including empty responses such as 204, are stored even if the client disconnects before receiving them.

Machine-Readable Error Codes

These three rejections set a stable ValidationFailure.ErrorCode so clients can distinguish them without parsing messages:

Constant in FinancialIdempotencyErrorCodes Error code
InProgress FinancialIdempotency.InProgress
PayloadMismatch FinancialIdempotency.PayloadMismatch
OutcomeUnknown FinancialIdempotency.OutcomeUnknown

The default ErrorResponse does not include these codes. To expose them in the code field of each ProblemDetails error, enable IndicateErrorCode:

app.UseFinancialIdempotency()
   .UseFastEndpoints(c => c.Errors.UseProblemDetails(o => o.IndicateErrorCode = true));

Custom error response builders also receive the code through each validation failure's ErrorCode property. See customizing error responses.

Broken storage contracts, such as returning a replay result without a stored response or starting a reservation without an ownership token, still return 500. They do not carry one of the three codes above.

How Long Requests Stay Protected

Completed responses are kept for DefaultDuration (overridden by the endpoint's Duration), starting when saved. After expiry, the same key can execute again.

Uncertain (unreplayable) outcomes are kept for the longer of UnreplayableRetention and Duration, starting when marked unreplayable. Set the global default with DefaultUnreplayableRetention (24 hours by default), or override it per endpoint:

FinancialIdempotency(o => o.UnreplayableRetention = TimeSpan.FromDays(7));

Active reservations never expire automatically.

Handling Failed Requests

An error does not necessarily mean that nothing happened. A payment provider could accept a charge and then time out before returning its response. Releasing the reservation in that situation would make a duplicate charge possible.

Exceptions, cancellation, ambiguous non-2xx responses and failures to capture or store the response retain protection against another execution. An exception handler cannot release the reservation. Check uncertain outcomes against business records or your payment provider and reconcile through your storage provider before retrying. If saving the outcome fails, the reservation may remain active without expiring.

If your application can prove that a rejected request made no business side effects, it can explicitly allow another attempt:

HttpContext.RejectFinancialIdempotencyWithoutSideEffects();
await Send.ErrorsAsync();

This declaration only takes effect when the request finishes normally with a non-2xx response. Validation failures do not make it automatically. Never call it after a payment timeout, an uncertain downstream result or a partially committed transaction.

Response Requirements

Financial endpoints buffer their responses rather than streaming them to the client. MaxResponseBodySize limits the response body to 128 MB by default. Exceeding this limit interrupts execution and keeps the reservation, so the original response may not reach the client.

Use ordinary buffered responses, not streaming or protocol upgrades. Do not disable buffering or replace response features.

If middleware uses OnStarting to change the response, register the callback before invoking the next middleware and access the current response through HttpContext.Response. Set or delete cookies before the captured response starts.

Cookies are sent with the first response but are not replayed. Replayed responses also exclude hop-by-hop headers and headers named by Connection.

Choosing Storage

The built-in memory store is useful for getting started. For production financial operations across restarts or multiple servers, implement IFinancialIdempotencyStore using durable storage.

For the memory store, configure InMemoryMaxEntries (10,000 by default) and InMemoryStoreSize (1 GB for completed bodies and headers). A full store rejects new reservations rather than evicting protected entries. These limits are shared by all callers.

A custom store must reserve operations atomically across servers and preserve ownership and retention guarantees when saving outcomes. Reconciliation of uncertain operations should be a separate administrative action, not part of an ordinary retry.

Deployment And Upgrades

The caller scope and request key are only part of identifying an operation. The HTTP method, scheme, host, path and selected additional headers also participate. Additional headers are empty by default, so credential rotation does not create a new reservation.

Keep forwarded-header configuration and host/path handling consistent across deployments. Changing these values can cause a retry to be treated as a new operation, bypassing an existing reservation.

Before upgrading a deployment with existing reservations, check for changes to operation identity, payload comparison or the storage contract. Such changes require a coordinated migration or draining and reconciliation of outstanding operations. Do not mix incompatible versions for the same operations.

© FastEndpoints 2026