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

# Idempotency

> Use idempotency keys to safely retry Karat Payout API batch requests after network errors without creating duplicate payments or recipients.

Network errors and timeouts can leave you unsure whether a request succeeded.
Idempotency lets you retry write requests safely: replaying a request with the
same key returns the original result instead of creating a duplicate.

## Using idempotency keys

For batch creation endpoints, include an `idempotencyKey` in the request body:

```bash theme={null}
curl https://payouts.api.trykarat.com/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payouts": [
      { "recipientId": "9c1f7b2a-3d4e-4f5a-8b6c-1d2e3f4a5b6c", "amount": 25000 }
    ],
    "idempotencyKey": "batch-2026-06-17-001"
  }'
```

Endpoints that support an `idempotencyKey`:

* [`POST /payments`](/api-reference/payments/create-a-payment-batch) — batch-level key
* [`POST /external-payments`](/api-reference/external-payments/create-external-payments) — batch-level key, plus an optional per-payment `idempotencyKey`

## Behavior

* Choose a unique key per logical operation (for example, a UUID or a stable
  identifier from your own system).
* Reuse the **same** key when retrying the **same** request.
* If you omit the key, the API generates one per request, so retries are **not**
  deduplicated — always supply your own key when retry safety matters.

<Note>
  Idempotency keys are most useful when paired with a retry strategy: on a
  timeout or `5xx`, retry with the same key using exponential backoff with
  jitter, and stop after a bounded retry window to avoid retry storms.
</Note>