Idempotent requests

Check supports idempotency for safely retrying requests without accidentally performing the same operation twice. This can be useful for issuing requests that you do not want to happen more than once, like attaching payroll item payments for an employee. You can retry the request with the same idempotency key to guarantee that no more than one entity is created.

To perform an idempotent request, provide an X-Idempotency-Key header to the request. We save the response's status code and body for the first request made with the given idempotency key regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

The format of the idempotency key is up to you, however we suggest using UUIDs.

X-Idempotency-Key: 8ac545e4-e918-4fb9-ac55-71edb1dec791

Key expiration

Idempotency keys expire after 24 hours. After a key expires, a new request with the same key will be treated as a new operation and will execute normally.

Retry strategy recommendations

The 24-hour expiration window is designed to cover the vast majority of retry scenarios, including short-term network failures and transient errors. When designing your retry logic, keep the following in mind:

• Immediate retries: Safe to retry at any point within the 24-hour window using the same idempotency key.
• Dead-letter queues: If your system uses a dead-letter queue where retries may happen after more than 24 hours, use a check-then-create pattern: first query the API to check whether the resource was already created (e.g., by listing payroll items for a given payroll), then only create the resource if it doesn't already exist. Use a new idempotency key for the retry.
• Key reuse after expiration: If you re-send a request with the same key after 24 hours, it will be treated as a new request. To avoid duplicate creation, always verify the current state of the resource before retrying after the expiration window.