Why you need this

Networks fail in the worst possible moment. You send a request to create an order, the connection times out, and you don't know whether the server processed it. If you retry blindly, you risk creating the same order twice.

An idempotency key solves this. You generate a unique string, send it with the request, and the API guarantees that the same key always returns the same result, no matter how many times you retry.

Send an idempotency key

Add the Idempotency-Key header to any request that creates or changes data:

curl "https://api.example.com/v1/orders" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: ord-2024-10-01-001" \
  -H "Content-Type: application/json" \
  -d '{"total": 42.50, "currency": "USD"}'

If the first attempt succeeded but the response was lost, the retry returns the original response instead of creating a duplicate.

The rules

  • Keys are remembered for 24 hours. After that, a reused key is treated as a new request.
  • Reusing a key with a different request body returns a 409 Conflict. That means you have a bug worth investigating, not a transient failure.
  • Generate a new key for every logical operation, not for every attempt. One key per user action, reused across retries.
  • Use UUIDs or a random string, so keys from different clients never collide.

What to do on a timeout

  1. Retry the exact same request with the exact same key.
  2. If you get 409 Conflict, compare the stored response. Something changed between attempts.
  3. Log the final request_id either way, so support can trace it.

Next steps