## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://help.trykarat.com/llms.txt)

Use this file to discover all available pages before exploring further.

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:

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

Endpoints that support an `idempotencyKey`:

- [`POST /payments`](https://help.trykarat.com/api-reference/payments/create-a-payment-batch) — batch-level key
- [`POST /external-payments`](https://help.trykarat.com/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.

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.