> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotent requests

> Retry any write safely with the Idempotency-Key header.

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`.

```bash theme={null}
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.

> [!TIP]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.