Course contentsShow
← Python
Lesson 817 of 1,06013. Data Integration and Web APIsFree lesson

Implementing Idempotency Keys for Reliable Operations

Learners will be able to prevent duplicate resource creation by generating and including unique idempotency keys in POST request headers.

In this lesson, you will learn how to prevent accidental duplicate resource creation by incorporating unique idempotency keys into your HTTP request headers.

The Problem with Network Instability

When building applications that perform state-changing operations—like charging a credit card or creating a database record—network timeouts can be dangerous. If you send a POST request to an API but don't receive a response due to a transient connection failure, you don't know if the server processed your request or if the request never arrived. If you simply retry the operation, you risk creating duplicate resources or double-charging a user.

The Idempotency Solution

An idempotency key is a unique identifier (typically a UUID) generated by the client and sent as a custom HTTP header. When the server receives a request with this key, it stores the result of that operation. If a subsequent request arrives with the exact same key, the server recognizes it as a retry and returns the cached result of the original operation rather than executing the logic a second time.

Implementing Idempotency in Python

To implement this, generate a unique ID using Python’s built-in uuid module before initiating your request using the requests library.

import uuid
import requests

# Generate a unique key for this specific transaction
idempotency_key = str(uuid.uuid4())

url = "https://api.example.com/v1/orders"
payload = {"item_id": 123, "amount": 50.00}

# Include the key in the request headers
headers = {
    "Idempotency-Key": idempotency_key,
    "Content-Type": "application/json"
}

try:
    response = requests.post(url, json=payload, headers=headers, timeout=5)
    response.raise_for_status()
    print("Operation successful:", response.json())
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}. Safe to retry with the same key.")

By passing the same idempotency_key during a retry loop, you ensure that the server-side logic remains safe, even if the connection fluctuates. The server sees the same key and maps it to the initial intent, ensuring your operations remain deterministic regardless of how many times the request is physically sent.

Key Takeaway: Always attach a unique UUID in a custom header when performing non-idempotent operations to ensure your retries are safe and produce no unintended side effects.