Skip to main content
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 '{
    "payouts": [
      { "recipientId": "9c1f7b2a-3d4e-4f5a-8b6c-1d2e3f4a5b6c", "amount": 25000 }
    ],
    "idempotencyKey": "batch-2026-06-17-001"
  }'
Endpoints that support an 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.