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

# Idempotency

> Retry any money request safely without paying twice.

Every request that moves money takes an `idempotency_key`. This applies to collections, payouts, batches, settlements and transfers.

* The key is 8 to 100 characters and must be unique within your business.
* **Same key, same body:** you get the original payment back, and nothing new happens. A replayed payout answers `200` with `replayed: true` instead of `202`.
* **Same key, different body:** you get `409 idempotency_key_reused`, and nothing new happens.

## Choose a key from your own records

Base the key on something that already identifies the payment in your system, such as an order, an invoice or a payroll line. Don't generate a fresh random key on each attempt: a retry would then look like a new payment.

```js theme={null}
const key = `payout-${invoice.id}`; // the same on every retry
```

If you deliberately want to pay again for the same order, for example after a failed attempt, use a new key such as `order-1042-attempt-2`.

## When to retry

| What happened | Retry with the same key? |
| - | - |
| Network error, timeout, no response | **Yes.** You'll get the original or a new payment, never two. |
| `5xx`, or `503 session_check_failed` | **Yes**, with backoff (1s, 2s, 4s…). |
| `429` | **Yes**, after waiting a few minutes. |
| `4xx` other than `429` | **No.** The request is wrong or not allowed, so fix it first. See the [error reference](https://docs.cloudpay.africa/errors/reference.md). |
| `202` with status `failed` later | Only with a **new** key, if you want to try again. |

Batch items each have their own `idempotency_key`, up to 60 characters. Each must be unique within the batch.


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