POST /v1/payroll/calculate and POST /v1/payroll/batch accept an Idempotency-Key
header. A retry after a timeout returns the original stored calculation instead of
writing a second one.
This matters more now that calculations are recorded. Without it, a network timeout on a
500-employee batch leaves you unable to tell whether you have one history or two.
Choosing a key
A good key is deterministic, so a retry produces the same one, and unique per logical calculation, so unrelated requests do not collide. Deriving it from the payroll run gives you both:Scoping
Idempotency keys are scoped to yourclient_id, not to the API key you presented.
Rotating a key mid-retry does not turn a replay into a new calculation, and it does not
hide the original from you. See Authentication.
Retrying a 503
503 PERSISTENCE_UNAVAILABLE means the calculation was not recorded, so no id and
no amounts came back. Retry with the same Idempotency-Key: if an earlier attempt did
land, you get that one rather than a duplicate.
This page covers idempotency for calculations. Payout creation has its own semantics,
including
external_id and the 409 conflicts — see
Payouts idempotency.