Area 08 · Backend · Concept 15 of 20

Idempotency Keys

A retried request with the same key is processed only once. No double charges.

11–20 · Production levelPhase 0 + 5 · Weeks 1–2, 18–20≈ 45 min

The idea

Networks fail after the server did the work but before the client got the response. The client retries, and now you have charged twice, sent two emails or created two documents. An idempotency key fixes this: the client sends a unique key with the request; the server stores the key with the result; a repeat with the same key returns the stored result instead of doing the work again.

Store keys with a TTL (24 hours is common), scope them per user, and handle the case where the first request is still in progress (return 409 or wait).

Agents need this too: if a run resumes from a checkpoint, tool calls with side effects should carry idempotency keys so they are not repeated.

Why it matters

Retries are everywhere in distributed systems; idempotency makes them safe.

Words to know

  • IdempotentDoing it twice has the same effect as doing it once.

Try it without code

Find risky endpoints

  1. List endpoints in your app that change something.
  2. Mark which would be harmful if run twice.

Use it in code

Idempotency middleware logic with Redis.

python
import json, redis
from fastapi import Header, HTTPException

r = redis.Redis(decode_responses=True)

def idempotent(user_id: str, key: str | None, do_work):
    if not key:
        return do_work()
    rkey = f"idem:{user_id}:{key}"
    if not r.set(rkey, "IN_PROGRESS", nx=True, ex=86400):      # someone already started
        stored = r.get(rkey)
        if stored == "IN_PROGRESS":
            raise HTTPException(409, "Request with this key is still being processed")
        return json.loads(stored)
    result = do_work()
    r.set(rkey, json.dumps(result), ex=86400)
    return result

# @app.post("/v1/refunds")
# def refund(body: RefundIn, idempotency_key: str | None = Header(None), user=Depends(current_user)):
#     return idempotent(user, idempotency_key, lambda: create_refund(body))
PRACTICE · TICK IT AFTER THIS

Add idempotency keys to your document upload endpoint and prove a retried upload creates one document.

Common mistakes

  • Keys not scoped per user.
  • Storing the key only after the work, leaving a race window.

Go deeper