Idempotency - Karat Help Center

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 existing batch instead of creating a duplicate. For POST /payments, a replay returns the existing batchId with an empty payouts array rather than repeating the original response payload.

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 '{
    "payouts": [
      { "recipientId": "9c1f7b2a-3d4e-4f5a-8b6c-1d2e3f4a5b6c", "amount": 25000 }
    ],
    "idempotencyKey": "batch-2026-06-17-001",
    "sourceAccountId": "4f266e59-5dae-49f7-9ef9-9bdf6d2b7c86"
  }'

Endpoints that support an idempotencyKey:

POST /payments — batch-level key
POST /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.
The first accepted POST /payments request for a key establishes the batch’s source account. Reusing that key with a different sourceAccountId does not switch the account.
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.

​Using idempotency keys

​Behavior

Using idempotency keys

Behavior