Idempotent requests - TagadaPay Documentation

A network error does not tell you whether the API received your request. Idempotency lets you send it again without charging twice.

Send a key

Every POST and PATCH that changes state requires an Idempotency-Key header. A request without it is refused with 400.

curl https://api.tagada.io/v1/payments \
  -H "Authorization: Bearer tsk_test_..." \
  -H "Payments-Version: 2026-11-01" \
  -H "Idempotency-Key: 6f1c2a8e-5b0d-4c47-9a3e-2d1f7b9c8e10" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1999, "currency": "USD", "store": "store_0123456789ab"}'

Use a value you generate once per operation, such as a V4 UUID. Up to 255 characters.
Do not put personal data in the key.
Keys are scoped to your account and mode (test or live). The same key in test and live is two different keys.
GET requests are safe by nature and take no key. POST /v1/eligible-methods is a read and takes no key either.

What happens on a retry

Situation	Answer
Same key, same method, path and body, first request finished	The result of the first request. For a created object, the API loads it again, so you get its current state. The `Payments-Idempotent-Replay` header tells you it was a replay.
Same key, first request still running	`409 idempotency_key_in_progress`. Retry later with the same key.
Same key, different method, path or body	`409 idempotency_key_reused`. Nothing runs.
The first request was refused for a temporary reason	The key is released. Retrying with it runs the request again.

Keys are kept for at least 24 hours. Use a new key for every new operation; never recycle one.

Retrying POST /v1/payments with the same key is also how a server gets the client_secret back if it lost the first response.

In the SDKs

The browser client, @tagadapay/core-js/payments-v3, sends a fresh UUID with every command and reuses it on its own retries. A new method call gets a new key.