Idempotency Errors

title: "Idempotency Errors — Handling Duplicate Request Detection" description: "Idempotency errors return 409 when a client retries a request with the same idempotency key but different data, preventing accidental duplicate operations." date: 2026-06-28 lastmod: 2026-06-28 weight: 27 tags: [apis, error-handling] }

Idempotency errors ensure that retrying the same request with an idempotency key returns the original result, while using the same key with different data returns a conflict.

What You'll Learn

• Idempotency key patterns
• Handling idempotency conflicts
• Preventing duplicate payment charges

Why It Matters

Idempotency prevents duplicate charges, orders, and resource creation when network issues cause retries.

Code Examples

// Idempotency conflict response
{
  "error": "IDEMPOTENCY_CONFLICT",
  "message": "Idempotency key 'key-abc123' was already used with different request data",
  "idempotency_key": "key-abc123",
  "previous_status": 201,
  "previous_response": {
    "id": "ord-456",
    "status": "created"
  }
}

# Idempotency middleware
from functools import wraps

idempotency_store = {}  # Use Redis in production

def idempotent(timeout=3600):
    def decorator(f):
        @wraps(f)
        def decorated(*args, **kwargs):
            idempotency_key = request.headers.get('Idempotency-Key')
            if not idempotency_key:
                return f(*args, **kwargs)

            existing = idempotency_store.get(idempotency_key)
            if existing:
                if existing['request_body'] != request.get_json():
                    return jsonify({
                        "error": "IDEMPOTENCY_CONFLICT",
                        "message": "Same key with different data",
                        "idempotency_key": idempotency_key
                    }), 409
                return jsonify(existing['response']), existing['status']

            response = f(*args, **kwargs)
            idempotency_store[idempotency_key] = {
                'request_body': request.get_json(),
                'response': response[0].json,
                'status': response[1]
            }
            return response
        return decorated
    return decorator

Common Mistakes

1. No Idempotency for Critical Operations

Payment, order creation, and any non-idempotent POST should support idempotency keys.

2. Expiring Keys Too Quickly

Keys should last 24 hours to cover extended network outages.

3. Not Returning Previous Response

Return the original response to the idempotent retry, not a conflict.

4. Different Data, Same Key

Return 409 when the same key is used with different request bodies.

5. Idempotency Without Persistence

In-memory stores lose data on restart. Use Redis or a database.

Practice Questions

1. What header is typically used for idempotency?
2. When should you return 409 vs 200 for idempotency?
3. How long should idempotency keys persist?
4. Why is idempotency critical for payment APIs?
5. How do you implement idempotency at scale?

Answers:

1. Idempotency-Key.
2. 200 when the same key+data; 409 when the same key+different data.
3. At least 24 hours.
4. Network retries could otherwise charge the customer multiple times.
5. Use Redis with TTL for fast, persistent idempotency storage.

Challenge: Implement idempotency for a payment API endpoint. Store keys in Redis, handle same-key retries, and detect key conflicts with different data.

FAQ