Search⌘ K
AI Features

Adding Idempotency to Prevent Duplicate Work

Explore how to implement idempotency in API endpoints to prevent duplicate processing and inconsistent results in retries. Understand how to define idempotency contracts, use unique keys and request hashes for deduplication, manage concurrency, and handle conflicts effectively to ensure reliable and predictable API behavior.

With a normalized error taxonomy in place, clients can now identify when a request has failed and whether it is safe to retry. Retries can overlap with in-flight requests, and clients can also submit the same request more than once. Next, we will prevent duplicate processing and unnecessary cost by adding idempotency controls to the endpoint.

A Support Ticket Assistant API sits behind a load balancer that retries when it hits a time-out. Often, that retry can arrive after the gateway has already finished the model call. Because the client never received the response, it replays the same request. Without an explicit idempotency rule, the gateway runs the work again and returns a second result.

That duplicate work is not just a financial cost. The same prompt and the same model identifier vendorX:model-family-2025-01-15 can produce two completely different valid completions for the same ticket. This means the eventual response a client sees can differ from the silently generated response that never made it back through the time-out. Today this endpoint still returns a hardcoded draft, making duplicates look harmless, but the inconsistency becomes user-visible the moment the stub is replaced with a real provider call. The error taxonomy already labels failures like provider unreachable, provider rate limit, and request timeout as retriable: true. Idempotency is what makes those retries actually safe at the HTTP boundary.

Define the idempotency contract

The contract starts with an idempotency key passed in an HTTP header named Idempotency-Key. This is generated by the client as an opaque string, such as a UUID. The gateway scopes the key by tenant, so uniqueness is enforced on the pair (tenant_id, idempotency_key), ensuring the same key from different ...