Skip to main content
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 your client_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.