Guides

Idempotency

Network hiccups happen. The Idempotency-Key header turns a maybe-twice operation into an exactly-once one.

The Idempotency-Key header

For supported endpoints, you can attach an Idempotency-Key header to any request. When you do, the server records the response under that key. If the same key comes back inside the next 24 hours, we return the cached response instead of re-executing the operation.

This lets you retry POSTs aggressively — when a request times out mid-flight, you don't know whether the server processed it or not. With an idempotency key, retrying with the same key either gets the original result (if it succeeded) or actually runs the operation (if it never reached us).

24-hour window

After 24 hours the cache entry expires and a same-key retry runs as a fresh operation. If you need longer-term de-duplication, store the response on your side keyed by your business identifier.

Supported endpoints

Today, idempotency is honoured on:

POST /api/v1/refunds — the highest-stakes mutation, and the one most likely to need a retry.

Other write endpoints will follow — see the changelog. Sending the header to an unsupported endpoint is harmless (we just ignore it), so you can safely attach it to every POST.

Recommended key format

A good idempotency key is unique per logical operation, not per HTTP attempt. If your code retries on its own — exponential backoff, queue redrive — every attempt for the same logical operation should send the same key. Two patterns work:

UUIDv4 per operation. Generate one when you first decide to do the thing, then carry it through every retry. crypto.randomUUID() in Node, uuid.uuid4() in Python.
Composite business key. Something like refund_2025_11_20_order_X9K2QF_001 — predictable, debuggable, and inherently unique to one decision.

Whatever pattern you pick, keys are limited to 255 characters of ASCII. Reuse a key for a different request body (same key, different payload) and we'll return 409 idempotency_conflict.

Example: retry-safe refund

bash

curl 'https://theyutes.com/api/v1/refunds' \
  -X POST \
  -H 'Authorization: Bearer tyk_••••••••••••••••••••••••••••••••' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: refund_2025_11_20_order_X9K2QF_001' \
  -d '{
    "orderId": "cl9j4k2l3000001jx8h2zfb1m",
    "amountKobo": 4500000,
    "reason": "damaged"
  }'

Run that command twice and the second invocation returns the original response without issuing a second refund. Your code can be as paranoid as it likes — the server stays consistent.