How to Implement an Idempotency Key API (Stripe Pattern)

Why retried POSTs cause duplicates

POST is not idempotent by design - calling it twice does the work twice. On unreliable mobile networks, HTTP clients retry aggressively, so a successful order creation that loses its response in transit becomes two orders in the database. Unique constraints catch some cases but they lose the original response, forcing the caller to do a separate GET just to find out what happened.

The standard solution, used by Stripe, AWS, and most payment APIs, is a client-supplied Idempotency-Key header: a UUID the client generates once for each logical operation and resends on every retry.

How it works

1. Client generates a UUID before the first attempt and sends it as Idempotency-Key.
2. Server processes the request, stores (key -> response), and returns the response.
3. On a retry with the same key, the server returns the cached response without re-executing the handler.

from flask import Flask, request, jsonify
import uuid

app = Flask(__name__)

IDEMPOTENCY = {}  # idempotency-key -> (status, body)

@app.route("/orders", methods=["POST"])
def create_order():
    body = request.get_json(force=True) or {}
    key = request.headers.get("Idempotency-Key")

    # Return the cached response if this key has been seen before
    if key and key in IDEMPOTENCY:
        status, payload = IDEMPOTENCY[key]
        return jsonify(payload), status

    # First request - do the real work
    order_id = str(uuid.uuid4())
    payload = {
        "order_id": order_id,
        "item": body.get("item"),
        "qty": body.get("qty"),
    }
    if key:
        IDEMPOTENCY[key] = (201, payload)
    return jsonify(payload), 201

Verify it works

# First POST - creates the order
curl -sX POST http://localhost:8000/orders \
    -H 'Idempotency-Key: abc-123' \
    -H 'Content-Type: application/json' \
    -d '{"item":"widget","qty":1}'
# {"order_id": "b4a7...", "item": "widget", "qty": 1}

# Retry with the same key - same order_id returned, no duplicate
curl -sX POST http://localhost:8000/orders \
    -H 'Idempotency-Key: abc-123' \
    -H 'Content-Type: application/json' \
    -d '{"item":"widget","qty":1}'
# {"order_id": "b4a7...", "item": "widget", "qty": 1}  <- identical

Both calls return the same order_id. The second call never touched the database.

Production considerations

• Use Redis, not a dict - an in-memory dict works for a single process but is lost on restart and doesn't span replicas. Redis with a 24-hour TTL is the standard production store.
• Scope the key to the caller - use (api_key, idempotency_key) as the composite cache key so two different users with the same UUID don't collide.
• Cache the full HTTP response - store status code + body (not just a row ID) so retries get a byte-for-byte identical response.
• Return 422 for key conflicts - if the same key arrives with a different request body, that is a client bug; return 422 Unprocessable Entity rather than silently returning the cached response for different data.