Concepts

Idempotency

Retry anything safely. Duplicates are impossible by design.

Every create endpoint accepts anIdempotency-Keyheader (up to 64 characters, your choice of format). If a request with the same key already succeeded, we return the original result — same payout ID, same body — instead of creating anything new.

POST /v1/payouts
Idempotency-Key: payroll-2026-07-batch1-row42

# network drops… retry with the SAME key
POST /v1/payouts
Idempotency-Key: payroll-2026-07-batch1-row42
→ 200 (original payout returned; nothing sent twice)

Reusing a key with a different payload is an error (409 idempotency_conflict) so a bug can’t silently bind two different payments to one key. Keys are scoped per environment and retained for 24 hours.