Idempotency keys for safe retries in Rest API

Introduction

Idempotency keys help make sure that when you send the same request multiple times, it only happens once. This stops mistakes like double payments or duplicate orders.

When a user clicks a button multiple times by accident and you want to avoid repeating the action.

When network problems cause a request to be sent again and you want to prevent duplicate processing.

When your system processes payments or orders and you want to ensure each is done only once.

When building APIs that clients might retry requests automatically.

When you want to keep your system safe from accidental repeated actions.

Syntax

Rest API

POST /api/orders HTTP/1.1
Idempotency-Key: unique-key-123
Content-Type: application/json

{
  "item": "book",
  "quantity": 1
}

The Idempotency-Key is a unique string sent in the request header.

The server uses this key to remember the request and avoid doing the same action twice.

Examples

Client sends a payment request with a unique idempotency key.

Rest API

POST /api/payments HTTP/1.1
Idempotency-Key: abc123
Content-Type: application/json

{
  "amount": 100
}

If the client sends the same request again with the same key, the server will not charge twice.

Rest API

POST /api/payments HTTP/1.1
Idempotency-Key: abc123
Content-Type: application/json

{
  "amount": 100
}

If no idempotency key is sent, the server treats each request as new and may process duplicates.

Rest API

POST /api/orders HTTP/1.1
Content-Type: application/json

{
  "item": "pen",
  "quantity": 2
}

Sample Program

This program creates a simple API that accepts orders with an Idempotency-Key header.

If the same key is sent again, it returns the saved response instead of creating a new order.

Rest API

from flask import Flask, request, jsonify

app = Flask(__name__)

# Store processed idempotency keys and their responses
processed_requests = {}

@app.route('/api/orders', methods=['POST'])
def create_order():
    idempotency_key = request.headers.get('Idempotency-Key')
    if not idempotency_key:
        return jsonify({'error': 'Idempotency-Key header missing'}), 400

    if idempotency_key in processed_requests:
        # Return the previous response to avoid duplicate processing
        return jsonify(processed_requests[idempotency_key])

    data = request.get_json()
    item = data.get('item')
    quantity = data.get('quantity')

    # Simulate order creation
    order_id = len(processed_requests) + 1
    response = {
        'order_id': order_id,
        'item': item,
        'quantity': quantity,
        'status': 'created'
    }

    # Save response with idempotency key
    processed_requests[idempotency_key] = response

    return jsonify(response)

if __name__ == '__main__':
    app.run(debug=True)

Important Notes

Time complexity: Checking and storing keys is usually O(1) with a hash map.

Space complexity: Stores keys and responses, so memory grows with unique requests.

Common mistake: Forgetting to require or check the Idempotency-Key header, which defeats the purpose.

Use idempotency keys when you want safe retries; use other methods like transactions for different guarantees.

Summary

Idempotency keys prevent duplicate actions by making repeated requests safe.

They work by sending a unique key with each request that the server remembers.

This is very useful for payments, orders, and any action that should happen only once.