Safe retrying of requests without accidentally performing the same operation twice
The API endpoints support idempotency for safely retrying requests without accidentally performing the same operation twice. When placing an order you must generate a unique key and send using the X-Idempotency-Key
header. Then, if a connection error occurs, you can safely repeat the request without risk of creating a duplicate order.
Runa’s idempotency works by storing the request body and response in a cache for a 30 day period. If the same request is made again with the same key, the response is returned or replayed from the cache instead of processing the request again. This behaviour is the same for any response regardless of whether it succeeds of fails. Subsequent requests with the same body and key return the same result including 4xx
and 5xx
errors.
We only retain this cache for 30 days. Orders requests using the same key after this period will result in a new order being placed.
The key can be any free-form string but we would suggest using a suitable unique and random value such as v4 UUIDs. This ensures the key is unique across all requests and reduces the risk of collisions. You should not use a string with intrinsic meaning such as an order ID or customer email address as you may need to generate a second request with a different key in case of the first returning an error.
When using idempotency there are a number of cases you will need to cover.
HTTP 102 Processing
response with type idempotency_in_progress
if the original request is still in progress. We are unable to replay the response until the original request has completed. Please wait a few seconds and try again.HTTP 400 Bad request
response with type idempotency_validation_error
if an idempotency key is reused but the request body does not match the original request. You should either correct the request body or generate a new key and try again.Currently only the order creation endpoint supports idempotency. You will note the X-Idempotency-Key
header is marked as required in the specification for this endpoint.
Safe retrying of requests without accidentally performing the same operation twice
The API endpoints support idempotency for safely retrying requests without accidentally performing the same operation twice. When placing an order you must generate a unique key and send using the X-Idempotency-Key
header. Then, if a connection error occurs, you can safely repeat the request without risk of creating a duplicate order.
Runa’s idempotency works by storing the request body and response in a cache for a 30 day period. If the same request is made again with the same key, the response is returned or replayed from the cache instead of processing the request again. This behaviour is the same for any response regardless of whether it succeeds of fails. Subsequent requests with the same body and key return the same result including 4xx
and 5xx
errors.
We only retain this cache for 30 days. Orders requests using the same key after this period will result in a new order being placed.
The key can be any free-form string but we would suggest using a suitable unique and random value such as v4 UUIDs. This ensures the key is unique across all requests and reduces the risk of collisions. You should not use a string with intrinsic meaning such as an order ID or customer email address as you may need to generate a second request with a different key in case of the first returning an error.
When using idempotency there are a number of cases you will need to cover.
HTTP 102 Processing
response with type idempotency_in_progress
if the original request is still in progress. We are unable to replay the response until the original request has completed. Please wait a few seconds and try again.HTTP 400 Bad request
response with type idempotency_validation_error
if an idempotency key is reused but the request body does not match the original request. You should either correct the request body or generate a new key and try again.Currently only the order creation endpoint supports idempotency. You will note the X-Idempotency-Key
header is marked as required in the specification for this endpoint.