Skip to content
Kurepay
Getting started

Idempotency

Safely retry create requests without risking duplicates. Send an Idempotency-Key and Collect will run the operation at most once, replaying the first response on any retry.

Sending a key#

Add an Idempotency-Key header (any unique string ≤ 255 chars — a UUID is ideal) to a POST:

curl https://kurepay.com/api/v1/invoices \
  -H "Authorization: Bearer ak_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c2e7a-1b2c-4d3e-9a8b-7c6d5e4f3a2b" \
  -d '{ "clientId": "…", "dueDate": "2026-07-01", "lineItems": [ … ] }'

How it behaves#

  • Keys are scoped per workspace and remembered for 24 hours.
  • A retry with the same key and the same body replays the original response verbatim, with an x-idempotent-replay: true header. The operation runs only once.
  • If the first request is still processing, a retry returns 425 idempotency_in_flight — wait briefly and try again.
  • Reusing a key with a different body returns 409 idempotency_conflict — generate a fresh key per distinct operation.

Use a new key for each logical create (e.g. one per row in an import). Reads (GET) are naturally idempotent and ignore the header.