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:
Code
The request body is the wallet-creation example from 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:
- Generate a unique key for each logical request. One key corresponds to one operation you intend to perform — one wallet, one payment, one withdrawal.
- 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.
- 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; use a new key for a new request |
| Key longer than 255 characters | 400 with error code idempotency-3001; 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; wait briefly and retry with the same key |
| Idempotency is temporarily unavailable | 503 with error code idempotency-0003; 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:
2xxresponses are recorded and replayed.401,403,429and5xxresponses are not recorded. Fix the problem (or wait, for rate limits) and retry with the same key. In rare cases the retry returns409withidempotency-0001; handle it as described under Behavior.- Most other
4xxresponses 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
Code
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. The exception is a 409 that persists beyond your retry window: reconcile before resubmitting, as described under Behavior.