Skip to main content

​
Overview

All POST endpoints require an Idempotency-Key header. The API guarantees that the same operation is performed at most once, regardless of how many times the request is sent. This protects against duplicate payouts and other unintended side effects caused by network retries. Requests that omit the header, or send a blank value, are rejected with 400 idempotency_key_required. GET requests are inherently idempotent. The header is silently ignored if sent on a GET.

​
Usage

Include the Idempotency-Key header on every POST request:
Keys can be any string up to 255 characters. V4 UUIDs work well, as do business-meaningful identifiers like an internal invoice ID. The SDK auto-generates a fresh idempotency key for every write request if you don’t provide one, so you get safe retries by default.

​
Replay behavior

When a request with a previously used idempotency key and identical parameters is received, the API returns the cached response from the original request. The Idempotent-Replayed: true header distinguishes a replay from a fresh creation:

​
Missing key

Requests that omit the Idempotency-Key header or provide an empty value return 400 Bad Request:

​
Mismatch behavior

Reusing an idempotency key with different request parameters returns 409 Conflict:

​
Concurrent requests

If a second request with the same key arrives while the first is still processing, the API returns 409 Conflict with code request_in_progress. Retry after a short delay. Once the original completes, retries will return the cached result.

​
Error handling

Only successful responses are cached. If a request fails (e.g. 400 validation error), the key is released and you can retry with the same key after fixing the request.

​
Key retention

Idempotency keys are retained for 30 days. After expiry, a previously used key is treated as new.

​
Key scoping

Keys are scoped globally across all endpoints per merchant account. Reusing the same key on a different endpoint returns the cached result from the first request or triggers a mismatch error. Different merchant accounts can use the same key independently.