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

# Retries and idempotency

> Retry requests without creating duplicate accounts or payments.

If a request times out, Ledig may have processed it even though you did not receive the response. Keep the original request and its identifiers so you can retry it safely.

Idempotency means repeating the same request returns the original result instead of creating another operation. The way you identify a retry depends on the endpoint.

## Choose the right retry method

| Operation | How to retry |
| - | - |
| `POST /v1/virtual-accounts` | Reuse the same `Idempotency-Key` and request body. |
| `POST /v1/wallets` | Reuse the same `Idempotency-Key` and request body. |
| `POST /v1/wallets/network` | Reuse the same key and body until you have a `requestId`. Then check that request's status. |
| `POST /v1/transfers` | Reuse the original quote ID and any reference you supplied. This endpoint does not use an `Idempotency-Key` header. |
| `POST /v1/quotes` | Reuse the original `reference` to recover that quote. Without a reference, a repeat can create another quote. This endpoint does not use `Idempotency-Key`. |
| `POST /v1/managed-businesses/applications` | Reuse the same `Idempotency-Key` and business name. |

For other write requests, check the endpoint instructions before retrying. Use a fresh timestamp and signature on every attempt, even when the body and retry key stay the same.

## Requests with an idempotency key

Generate a unique `Idempotency-Key` for each new operation. A UUID works well. Store it with the request body and the business making the request.

For example, your application can generate a key in Node.js:

```js theme={null}
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID();
// Save this key with the request. Reuse it if the response is lost.
```

Send that key in the `Idempotency-Key` header. If you retry with the same key and body, Ledig returns the original result. Changing the body while keeping the key returns a conflict.

For receiving accounts, `intent: additional` requests another account; it does not recover an earlier request. A pending request may need more time or review before it completes.

## Quote replay

Save your quote's `reference`, ID and expiry. Repeating the same reference for your business returns the original quote with HTTP `201` and top-level `replayed: true`. It does not refresh its price, status or expiry. A newly created quote returns `replayed: false`.

An accepted or expired quote can still be returned by a replay. Use a fresh reference when you deliberately need a fresh quote. If you have already submitted a transfer with the original quote, resolve that payment's outcome first.

## Transfer replay

Keep the original `quoteId` and any `reference` after a transfer request times out. Retrying them for the same business recovers the original transfer.

* Reusing a reference with a different quote returns the original transfer and leaves the new quote unused.
* Reusing a quote with a new, unused reference returns the original transfer. It does not attach the new reference to that transfer.
* If the quote and reference point to two different transfers, Ledig returns `409 IDEMPOTENCY_CONFLICT`.

Read the known transfer to confirm its status before creating another payment. See [Transfers](https://docs.ledig.io/guides/transfers.md#retries) for more examples.

Both new and replayed transfer responses use HTTP `201`. Top-level `replayed: true` means the original transfer was returned without creating another payment; `false` means a new transfer was created. HTTP acceptance does not confirm delivery.

## When to retry or stop

For temporary read failures, wait before retrying and increase the delay after each failed attempt. Follow `Retry-After` when it is returned.

For writes, use the retry method above and limit the number of attempts. Correct a rejected request before sending it again, but check any uncertain earlier attempt first.

If you still cannot confirm the result, contact [support@ledig.io](mailto:support@ledig.io) with the request ID and relevant account, wallet or transfer ID.


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