Idempotency
Safely retry write requests without creating duplicates
Network failures, timeouts, and worker restarts make retries unavoidable. The Idempotency-Key header lets you retry a write request without risking duplicate side effects: the first successful response is cached for 24 hours, and any subsequent request with the same key is replayed verbatim from cache.
Send Idempotency-Key on every state-changing request where a duplicate would be problematic — creating invoices, posting payments, bulk imports, etc.
The header is optional. If omitted, the request is processed normally without idempotency protection.
Idempotency-Key header.Content-Type: application/json (JSON tier) — body is compared using a SHA-256 hash:
X-Idempotent-Replayed: true.422 Unprocessable Entity (catches accidental key reuse with mutated payload).422 Unprocessable Entity, since the binary body cannot be hashed to confirm it matches the original. Use a new key for a new request.409 Conflict. Retry after the original completes.If the same request is retried with the same Idempotency-Key and body, the response is identical, no new invoice is created, and the response includes:
Invalid keys are rejected with 400 Bad Request.
Idempotency-Key value can be safely reused across different endpoints — they will not collide.Idempotency-Key takes effect on all POST requests under /v1/*. Each endpoint that supports it lists Idempotency-Key in its parameter table — refer to the per-endpoint API reference.
The header is ignored (no caching) for:
POST methods (GET, PATCH, PUT, DELETE — currently)For multipart file uploads and other non-JSON content types, the server cannot verify the request body without loading the full upload into memory. A retry with the same key always returns 422 — use a new key for each new upload.