# Idempotent Requests

The Tesser API supports idempotent requests, which let you safely retry a request without performing the same operation twice. If a request times out or your connection drops before you receive a response, send it again with the same idempotency key. If the original request completed, you get its result back instead of, for example, a second wallet or a second payment.

## Using the `Idempotency-Key` header

To make a request idempotent, send an `Idempotency-Key` header with a unique value. A version 4 UUID is recommended. Any unique string of at most 255 characters works; a longer key is rejected with `idempotency-3001`:

```bash
curl --request POST \
  --url https://api.tesser.xyz/v1/accounts/wallets \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 4f9d2c1a-7b3e-4a8f-9c21-d5e6f7a8b9c0' \
  --data '{
    "name": "Treasury Wallet (Omnibus)",
    "type": "stablecoin_ethereum",
    "is_managed": true,
    "signature": "eyJwdWJsaWNLZXkiOiJwdWJfZXhhbXBsZSIsInNpZ25hdHVyZSI6InNpZ19leGFtcGxlIiwic2NoZW1lIjoiRUQyNTUxOSJ9"
  }'
```

The request body is the wallet-creation example from [Create an Account](/how-tos/create-an-account); the `signature` value shown is a placeholder, so generate a real signature for your own request.

The header is optional. Requests without it behave normally and are not protected against duplicate submission.

Follow these rules:

1. **Generate a unique key for each logical request.** One key corresponds to one operation you intend to perform — one wallet, one payment, one withdrawal.
2. **On retry, reuse the same key with the identical request.** The key is bound to the endpoint, the exact request body and the query string it was first used with. Serialize the body once and resend the same bytes; sending a different body or query string under the same key is rejected.
3. **Never reuse a key for a different request**, including on a different endpoint. Keys are shared across all endpoints in your workspace, so a key already used elsewhere is rejected as a mismatch.

Keys are kept for 24 hours and are scoped to your workspace, so they cannot collide with another organization's keys. After 24 hours a key may be treated as new, so a late retry can run the operation again. Retry within 24 hours; after that, check whether the operation took effect before sending it again. Never reuse a key for a different operation, even after 24 hours.

## Behavior

| Scenario | Result |
| --- | --- |
| First request with a key | Processed normally; the response is recorded |
| Retry with the same key and body, after the original completed | The original response is replayed; nothing is executed again |
| Same key with a **different endpoint, body or query string** | `400` with error code [`idempotency-0002`](/overviews/errors/platform#idempotency); use a new key for a new request |
| Key longer than 255 characters | `400` with error code [`idempotency-3001`](/overviews/errors/platform#idempotency); the request was **not** processed, so retry with a shorter key |
| Same key while the first request is **still processing** | `409` with error code [`idempotency-0001`](/overviews/errors/platform#idempotency); wait briefly and retry with the same key |
| Idempotency is temporarily unavailable | `503` with error code [`idempotency-0003`](/overviews/errors/platform#idempotency); the request was **not** processed, so retrying with the same key is safe |

If a `409` with `idempotency-0001` persists beyond your retry window, do not assume the operation failed or succeeded. Check whether it took effect (for example, list the resource you were creating) and resubmit only if it did not. The key frees up within 24 hours.

## Which responses consume a key

Not every response "uses up" a key:

- **`2xx` responses are recorded and replayed.**
- **`401`, `403`, `429` and `5xx` responses are not recorded.** Fix the problem (or wait, for rate limits) and retry with the same key. In rare cases the retry returns `409` with `idempotency-0001`; handle it as described under [Behavior](#behavior).
- **Most other `4xx` responses are recorded and replayed for 24 hours.** The same key can return the same error even after you fix the cause, so send the corrected request with a new key.

## Supported endpoints

Every authenticated `POST` and `PATCH` endpoint accepts the `Idempotency-Key` header, with the behavior described above. `GET` and `DELETE` requests ignore the header.

Idempotency keys are strongly recommended wherever a duplicate submission would create a duplicate resource or move funds twice:

| Area | Endpoints |
| --- | --- |
| Accounts | `POST /v1/accounts/wallets`, `POST /v1/accounts/banks`, `POST /v1/accounts/ledgers`, `POST /v1/accounts/generic`, `POST /v1/accounts/{id}/onchain-addresses`, `PATCH /v1/accounts/{id}` |
| Tenants and counterparties | `POST /v1/entities/tenants`, `POST /v1/entities/counterparties` |
| Payments | `POST /v1/payments`, `PATCH /v1/payments/{paymentId}`, `POST /v1/payments/{paymentId}/review`, `POST /v1/payments/{paymentId}/steps/{stepId}/sign` |
| Treasury | `POST /v1/treasury/deposits`, `POST /v1/treasury/withdrawals`, `POST /v1/treasury/rebalances`, plus the withdrawal and rebalance `/steps/{stepId}/sign` endpoints |
| Sandbox simulation | `POST /v1/treasury/deposits/{id}/simulate` |

## Recommended retry pattern

```text
key = uuid4()                     # generate once, before the first attempt
persist key alongside your own record of the operation
loop with backoff (e.g. 1s / 2s / 4s):
    send the request with Idempotency-Key: key
    2xx                        -> done (the original result or its replay)
    5xx or timeout             -> retry with the same key and body,
                                  unless the error_message says
                                  retrying won't help
    409 idempotency-0001       -> wait briefly, retry with the same key
    503 idempotency-0003       -> retry with the same key (nothing was processed)
    401, 403, 429              -> fix the problem (or wait, for 429), then
                                  retry with the same key
    other 4xx                  -> recorded; fix the request and send it
                                  with a new key
```

With this pattern, a retry of a request that completed returns the recorded result instead of running the operation again. Whether a retry can succeed at all depends on the error: see [Retrying a Request](/overviews/errors#retrying-a-request). The exception is a `409` that persists beyond your retry window: reconcile before resubmitting, as described under [Behavior](#behavior).
