Idempotency key

API Design

Meaning

An idempotency key is a client-generated unique identifier attached to a mutating API request so the server can recognize and discard duplicate retries of the same operation. It addresses the pain point where network failures, timeouts, or client retries can cause the same action (e.g., a payment charge) to execute multiple times. Developers reach for it whenever a request is non-safe and a retry could produce duplicate side effects.

Primary Function

API design

Communicative Purpose

Prevents duplicate side effects when clients retry non-idempotent operations due to network failures or timeouts.

Pattern

client generates unique key → attaches to mutating request → server stores key+result → retries with same key return cached result

Função primária

API design

Propósito comunicativo

Prevents duplicate side effects when clients retry non-idempotent operations due to network failures or timeouts.

Situações de gatilho

Payment processing: ensuring a retried charge does not create duplicate transactions; Distributed systems: deduplicating messages across at-least-once delivery channels; Webhook handling: distinguishing new events from redeliveries

Contextos

REST APIs, payment gateways (Stripe, PayPal), message queues, webhook receivers, distributed transaction systems

Padrão

client generates unique key → attaches to mutating request → server stores key+result → retries with same key return cached result

Colocados típicos

HTTP headers (Idempotency-Key)
request middleware
deduplication stores (Redis)
retry policies
at-least-once delivery

Substituições comuns

Optimistic locking with version numbers: requires server-side state and does not dedupe across processes
Natural deduplication via business keys: only works when a natural unique constraint exists
Exactly-once messaging: stronger guarantee but heavier infrastructure

Erros comuns

Reusing the same key for logically different operations: causes the second operation to silently return the first's cached result; Storing idempotency keys forever: unbounded storage growth; Using non-UUID keys with insufficient entropy: collision risk allows duplicate processing; Treating GET requests as needing idempotency keys: GET is already idempotent by HTTP spec; Not scoping keys per-resource or per-tenant: cross-tenant collisions return wrong cached responses

Similar / contraste

Request ID: tracks a request for tracing/logging, not deduplication; Transaction ID: groups related operations, does not prevent duplicates; Optimistic concurrency token: prevents stale writes, not duplicate writes

Interferências

Coming from functional programming: may conflate 'idempotent' with pure functions — idempotency keys are about retry safety, not referential transparency; Coming from SQL: may think UNIQUE constraints suffice — they prevent duplicates at storage but not at the API/operation level

Família do chunk

Idempotency
at-least-once delivery
retry policies
request deduplication
HTTP idempotent methods

Nuance

When NOT to use: safe methods (GET, HEAD, OPTIONS) are already idempotent by HTTP spec and need no key; Performance: requires server-side storage (typically Redis with TTL) for the key→result mapping, adding latency and memory cost; Boundary: keys must be scoped per-endpoint and per-tenant to avoid cross-contamination, and TTL must exceed the maximum retry window

Efeito pragmático

Enables safe client-side retries without risk of duplicate charges, duplicate orders, or duplicate notifications — critical for financial APIs and any system where duplicate side effects have real-world cost.

Dica de memória

Like a coat check ticket for API requests — hand it in, and even if you lose your receipt and ask again, you get the same item back instead of a second copy.

Upgrade path

Exactly-once semantics in message brokers (Kafka transactions, RabbitMQ publisher confirms)

Frequência: MediumFormulaicidade: FlexiblePrioridade de aquisição: Recognition firstPrioridade de output: BothTag de espaçamento: Medium-term

Examples

import uuid import requests idempotency_key = str(uuid.uuid4()) response = requests.post( "https://api.example.com/v1/charges", headers={"Idempotency-Key": idempotency_key, "Authorization": "Bearer token"}, json={"amount": 2000, "currency": "usd", "source": "tok_visa"}, ) # Retry safely with the same key if the first call timed out retry = requests.post( "https://api.example.com/v1/charges", headers={"Idempotency-Key": idempotency_key, "Authorization": "Bearer token"}, json={"amount": 2000, "currency": "usd", "source": "tok_visa"}, ) assert retry.json()["id"] == response.json()["id"]

from fastapi import FastAPI, Header from pydantic import BaseModel import redis app = FastAPI() cache = redis.Redis() class TransferRequest(BaseModel): from_account: str to_account: str amount_cents: int @app.post("/transfers") def create_transfer( payload: TransferRequest, idempotency_key: str = Header(..., alias="Idempotency-Key"), ): cached = cache.get(f"idem:{idempotency_key}") if cached: return cached.decode() result = process_transfer(payload) cache.setex(f"idem:{idempotency_key}", 86400, result) return result

import json from kafka import KafkaConsumer consumer = KafkaConsumer("orders", group_id="fulfillment") seen_keys = set() for message in consumer: event = json.loads(message.value) key = event["idempotency_key"] if key in seen_keys: continue # Skip duplicate redelivery fulfill_order(event) seen_keys.add(key)