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

# Idempotency

> Retry any write safely with an Idempotency-Key.

Networks fail. A request can time out after Talescria has already opened the account or sent the payment. To make retries safe, send an `Idempotency-Key` header: retrying with the same key returns the first answer instead of doing the work again.

```http theme={null}
POST /v1/transfers
Idempotency-Key: pay_inv_4821_attempt
```

## Which requests need one

These writes **require** a key, and are refused with `400 IDEMPOTENCY_KEY_REQUIRED` without one:

* Open an account: `POST /v1/accounts`
* Create a recipient or a destination: `POST /v1/recipients`, `POST /v1/recipients/{id}/destinations`
* Send a payment: `POST /v1/transfers`
* Transfer between your accounts: `POST /v1/conversions`
* Create a payment link, customer, invoice or recurring series

Every other write accepts one too.

## How keys behave

| You send | You get |
| - | - |
| A new key | The request runs. |
| The same key and the same request | The first response again, with `Idempotent-Replayed: true`. Nothing is created or sent twice. |
| The same key while the first request is still running | `409 IDEMPOTENCY_IN_PROGRESS`, with `Retry-After`. Retry shortly. |
| The same key with a different request | `422 IDEMPOTENCY_KEY_REUSED`. Use a new key. |

"The same request" means the same method, path and JSON body (key order doesn't matter).

If a request fails on our side with a `5xx`, or the connection drops before a response, the key is released so your retry runs again. A `2xx` or `4xx` response is the answer for that key.

Keys are kept for **24 hours** and are scoped to your OAuth client: two clients can't collide.

## Choosing keys

* **One key per operation, not per attempt.** Generate the key when you decide to make the payment, store it with your record, and reuse it on every retry. A fresh key per attempt defeats the purpose.
* **Format:** 8 to 255 characters from `A–Z a–z 0–9 - _ : .`. A UUID works well. For transfers between your accounts, keep it to 100 characters.
* **Derive from your own IDs** where that's natural, for example `payout:invoice_4821`, so the same business action can never produce two payments.

```python theme={null}
import time
import uuid
import requests

def send_payment(token, payment):
    # The key is stored with the payment, so every retry reuses it.
    key = payment.idempotency_key or str(uuid.uuid4())
    payment.save_key(key)
    for attempt in range(5):
        try:
            resp = requests.post(
                "https://api.talescria.com/v1/transfers",
                headers={"Authorization": f"Bearer {token}", "Idempotency-Key": key},
                json=payment.body(),
                timeout=30,
            )
        except requests.RequestException:
            time.sleep(2 ** attempt)  # Same key: safe to retry.
            continue
        if resp.status_code in (409, 429) or resp.status_code >= 500:
            time.sleep(int(resp.headers.get("Retry-After", 2 ** attempt)))
            continue
        return resp
    raise RuntimeError("payment request didn't complete; retry later with the same key")
```

> [!NOTE]
>
> For payments and transfers between your accounts, the key is also attached to the money movement itself, so money can't move twice even if a request is interrupted part way through.


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