Idempotency - Karat Help Center

Documentation Index

Fetch the complete documentation index at: /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 — 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.
• 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.