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://paytrum.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: trueheader. 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.