Making Idempotent Requests

Understanding Idempotency

Idempotent requests produce the same response even if the the operation is repeated multiple times. Rutter supports making idempotent POST and PATCH requests for safely retrying requests without duplicating the operation. GET and DELETE requests are always idempotent by design.

To make an idempotent request when creating objects using Rutter's API, provide a unique Idempotency-Key in your request headers. This key is used to identify the request and ensure that the operation is only performed once. If the same idempotency key is used for multiple requests, only the first request will be processed.

We recommend using a V4 UUID for the idempotency key.

Detailed Behavior

Idempotency works by saving the result of the first accepted request, regardless of whether the request succeeded or failed. As a result, idempotent requests are safe to replay due to the request not being processed by Rutter due to a network or connection issue. However, idempotency does not help in the case of a returned error response. If the outcome of the initial request is an error, retrying the request with the same key will deterministically return the same error.

A subsequent request with the same Idempotency-Key but a different request body or parameters will error with a 409 Conflict if the initial request has already been accepted.

A request is only considered accepted if it passes Rutter's initial validation checks. This includes authentication, authorization, and a series of payload validation checks that differ per platform and endpoint. To identify whether a request has been accepted, you can check the response headers of your request for an X-Rutter-Job-ID. Requests that have been accepted will have this header present, while requests that have been rejected will not. Rejected requests will always have a non 2xx response code.

A request that is not accepted can be retried without changing the Idempotency-Key.