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

# Idempotency

> Safely retry requests without creating duplicate operations.

## Overview

A timeout or dropped connection can leave you unsure whether a request reached Lead. Send an `Idempotency-Key` header and you can retry the same request as many times as you need. If the first attempt succeeded, Lead returns the same response again and takes no new action. If it failed, Lead evaluates the retry as a new request.

One rule governs everything on this page: **Lead caches only successful (2xx) responses. Errors are never cached.**

## Sending a key

Include an `Idempotency-Key` header with a value you generate.

```bash theme={null}
curl --request POST \
     --url https://api.sandbox.lead.bank/v2/wires \
     --header 'Idempotency-Key: 9c1a2f3e-7b4d-4e8a-9f10-2d6c8e5a1b47' \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{ ... }'
```

* **Format.** Any string up to 255 characters. Lead recommends a v4 UUID or another random value.
* **Scope.** A key is scoped to one endpoint within one program. The same string on `POST /v2/wires` and `POST /v2/entities` does not collide, and keys in one program never collide with keys in another.
* **Expiry.** A key is valid for 48 hours from the original request. After that, Lead treats the same key as a new request.

## Which endpoints accept a key

All mutative endpoints require an `Idempotency-Key`. The [API reference](/api-reference/using-the-api/authentication) lists the header on every endpoint that supports it and marks whether it is required. Lead recommends sending a key on every request that creates an object, whether or not the endpoint requires one.

A request without the header to an endpoint that requires it returns `400 idempotency_key_missing`.

## How Lead handles a repeated key

| Scenario | Result |
| - | - |
| Same key, same body, original returned 2xx (including 202) | Lead returns the original response with `Idempotency-Replayed: true`. No new side effects. |
| Same key, same body, original returned any 4xx or 5xx | Lead runs the request again as if the key were new. |
| Same key, different body | `422 idempotency_request_inconsistent` |
| Same key, original request still in flight | `409 idempotency_key_in_use`. Wait for the first request to finish, then retry. |
| Key older than 48 hours | Lead treats it as a new request. |

The replayed response is byte-for-byte the original, including `id`, `status`, and timestamps as they were at creation. To see the object's current state, retrieve it by `id`.

## Retrying after an error

Because Lead never caches an error, you do not need to rotate to a new key before retrying. Fix the request if the error was yours (a `400` or `422` naming a field), or simply resend if the condition was temporary. For example, a request rejected with `non_sufficient_funds` can be retried with the same key once the balance is covered.

If you built key-rotation logic against v0 or v1, where some 4xx responses were cached, you can remove it on v2.

## Asynchronous requests

Many payment creates return `202 Accepted` and then settle, reject, or return later. Idempotency covers the create, not the outcome. A `202` is cached as a success, and a later downstream failure does not invalidate it; retrying the same key returns the original `202`. Track the outcome through webhooks or by retrieving the object.

## Related

* [API Errors](/api-reference/using-the-api/errors-v2): the `idempotency_*` codes above and every other code v2 returns
* [Webhooks](/api-reference/using-the-api/webhooks): how to learn the final state of an asynchronous request


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