Idempotency

About Idempotency

Network timeouts, connection drops, and automatic retry behaviour are a fact of life. If a request changes server state (for example POST, PATCH, PUT, DELETE), retrying the same request can accidentally apply the change more than once.

To make retries safe, this API supports idempotency keys.

How idempotency works in this API

For supported mutating endpoints, you can include an Idempotency-Key request header:

Idempotency-Key: <unique-value>

When you send an idempotency key:

First request with a new key

We execute the operation.

We store the response associated with that key.

We return the response.

Subsequent requests with the same key (within 30 days)

We do not execute the operation again.

We return the previously stored response.

This allows you to safely retry requests without creating duplicate resources or duplicating side effects.

Retention window (30 days)

Idempotency keys are retained for 30 days.

If you retry with the same key within30 days, you’ll get the original response.

If you reuse the same key after 30 days, the key may no longer be recognised and the request may execute again (which may cause mutating side effects).

We guarantee that we will honour idempotency keys for at least 30 days. After this point we reserve the right to respect the keys for any further length of time and this behaviour must not be relied upon.

Only reuse a key for retries of the same logical operation. Reusing a key for a different operation within the 30-day window can cause you to receive a stored response that does not match your new request.

When to send an idempotency key

We strongly recommend sending an idempotency key for:

POST requests that create resources (orders, submissions, payments)

any endpoint that triggers irreversible or costly side effects

any request your client may retry automatically

For GET requests, idempotency keys are typically unnecessary.

Generating idempotency keys

An idempotency key should be:

Unique per logical operation (one key per “user action” or per business transaction)

Stable across retries of that operation

Opaque (do not embed personal data or secrets)

Recommended: UUID v4

A random UUID v4 is the simplest and most widely interoperable choice.

Examples:

7d2b3f0c-8e66-4d9c-9a2c-4f6e3b2f5b21

d7f59c3a-13c2-4f2f-8d3d-0d1a2f9a3b7c

Common generation options:

.NET: Guid.NewGuid()

Java: UUID.randomUUID()

JavaScript: crypto.randomUUID()

Python: uuid.uuid4()

Alternatives (also acceptable)

ULID / KSUID (sortable identifiers)

Cryptographically random bytes encoded as Base64URL

Example: Salary Deduction Confirmation Submission

Authentication: x-api-key and Authorization: Bearer [access-token]

Path parameters: payroll_id and batch_id (18 digits)

Idempotency-Key: up to 128 characters, for this payroll and batch

JSON body: a deduction_data_confirmation object with batch_id, payroll_id, total_amount (in the currency's minor unit, e.g. 455 = £4.55), employee_count, pay_date, currency and deduction_data

Request with `Idempotency-Key`

What happens on retry?

If your client does not receive a response (for example due to a timeout), you can retry the request using the same Idempotency-Key.

If the key has not been used before: we execute the request and return the result.

If the key has been used within the last 30 days: we return the previous result and do not execute again.

If a request with the same key is still being processed, we return 409; retry shortly.

Client retry guidance

Generate one idempotency key per logical operation.

Persist that key until you receive a definitive success or failure response.

When retrying, send the same method, path, and payload along with the same Idempotency-Key.

Retry only on transient failures (timeouts, connection errors, 5xx responses).

Endpoints you host

Ontime sends an Idempotency-Key header on the Salary Deduction Enablement and Salary Deduction Employee Data Push requests it makes to you, and sends the same key when it retries a request. Honouring it is optional.

Summary

Send Idempotency-Key with mutating requests you may need to retry.

We execute once per key and replay the stored response on subsequent uses within 30 days.

Keys are retained for 30 days; reuse after that may cause the operation to execute again.

Idempotency

About Idempotency#

How idempotency works in this API#

Retention window (30 days)#

When to send an idempotency key#

Generating idempotency keys#

Recommended: UUID v4#

Alternatives (also acceptable)#

Example: Salary Deduction Confirmation Submission#

Request with Idempotency-Key#

What happens on retry?#

Client retry guidance#

Endpoints you host#

Summary#