Skip to content

Retries and idempotency ​

A network failure can leave you unsure whether a request went through. Retrying a create blindly can make a duplicate.

The REST API has no general idempotency key — no Idempotency-Key header. The one exception is creating a payment message (v04 beta), which accepts an Idempotency-Key header: see Payment channels and Limits. Otherwise idempotency is endpoint-specific; this page collects what makes a retry safe.

Give your records your own id, and look before you create ​

Set your system's id on what you create, then search for it before creating again.

ObjectYour id goes inFind it again with
Employmentinfo.sourceIdGET /v03/api/employments?$filter=externalId eq 'ID98765432' — sourceId is indexed as externalId

For employments this also prevents a duplicate worker record: store info.workerAccountId from the first response and send it on any later employment for the same person — see Create employees.

Safe to repeat ​

  • Re-reporting an invoice's current status is a safe no-op — see Invoices and payments.
  • Reads (GET) are always safe.

Never repeat blindly ​

  • Committing a payroll for payment. A calculation that is already paymentStarted cannot be committed again, and a paymentSucceeded one is never paid twice — but check the status before you retry. See Set for payment.

On the MCP server ​

On the authenticated MCP server, calculation rows added with a sourceId replace rows added earlier with the same id — so repeating the same request does not double the rows. Employment default rows and rows added by hand are left alone.

Checklist ​

  • Every object you create carries your own id where the API allows one.
  • A retry after a timeout searches before it creates.
  • Payment commits are checked by status before any retry.

Every page is also available as Markdown: add .md to its URL — a folder page such as white-label/ is white-label/index.md. Index for LLMs: llms.txt. Questions: Support.