Skip to main content
A write that times out has still reached the provider. Retrying it blind creates a second record in your customer’s system, and someone has to find and remove it by hand. X-Idempotency-Key makes the retry safe: send the same key with the same body and Bindbee returns the saved result instead of writing again. Four HRIS write endpoints accept the header:
  • POST /api/hris/v1/employees
  • POST /api/hris/v1/employee-payroll-runs
  • POST /api/hris/v1/time-off
  • POST /api/hris/v1/timesheet-entry
Passthrough does not accept it, so a retried passthrough write reaches the provider as a second write.

​
Sending an idempotent request

The header is optional. Requests without it are processed independently and carry no protection against duplicate execution.

​
Choosing a key

Generate one opaque key per logical creation, and reuse it only when retrying that same creation. A UUID works, and so does a value derived from your own record identity:

​
How Bindbee responds

The two conflicts are distinguishable by their detail:
On the first, wait briefly and retry the same key. On the second, check the body: use a new key only when the change represents a genuinely new record.
A replayed response can carry a different status code from the original, so treat any 2xx as confirmation that the write succeeded rather than matching on 201 or 200.

​
The five-minute window

Bindbee saves a successful response for five minutes. Within that window the same key and body returns the saved result. After it, the key may be treated as new. Failed attempts are not saved, so the same key can be retried after a failure.
The key is not a permanent record of a write. Five minutes after a successful creation, sending the same key again can create a second record - store the returned ID against your own record rather than relying on the key.

​
Retrying safely

  1. Generate the key before the first request, and store it with the operation you are attempting.
  2. Send the write with that key.
  3. On a network error or a 5xx, retry the same body with the same key.
  4. On an in-progress 409, wait briefly and retry with the same key.
  5. On a different-payload 409, check the body before deciding whether this is a new record.
  6. Stop once you have a 2xx.
Where the outcome is uncertain, retry the same key first. Each new key is a new creation request, so cycling through keys is how duplicates get made.