Trice supports optional idempotency to make write operations safe to retry. This is especially useful for handling network timeouts, retries, or duplicate requests.

How to Use It

Include the following optional header with your POST, PUT, or DELETE requests:

X-TRICE-IDEMPOTENCY-KEY: <uuid>

The value must be a UUID (UUID v4 recommended) and should be unique per logical request.

How It Works

The first time Trice receives a request with a given combination of:

idempotency key
HTTP method (i.e. PUT, POST, DELETE)
request body (if applicable)
Trice-specific request headers
your account ID (obtained from the access token)

…the system processes the request and persists the idempotency key, the response body, and the HTTP response status code (e.g. 200)

Subsequent requests with the same idempotency key, request body, HTTP method, and headers will not re-execute the operation. Instead, Trice will return the same response body and HTTP status code as the original request.

The response header x-trice-idempotency-replayed: trueindicates that the request has been replayed.

Conflict Handling

If you reuse an idempotency key with different request headers and/or a different request body, the API will reject the request with HTTP 409 code and error message:

Conflict error, The request details do not match a previous request with same idempotency key.

Concurrent Requests

If multiple requests using the same idempotency key are received at the same time, and the original request has not finished processing yet, the API may respond with HTTP 409 code and error message:

Actively processing previous request

Important Notes

Key expiration: Idempotency keys are automatically removed after 30 days. After expiration, the same key may be reused as a new request
Idempotency is not enforced if the X-TRICE-IDEMPOTENCY-KEY header is not included
Always reuse the same request body and headers when retrying a request with an idempotency key