> ## Documentation Index
> Fetch the complete documentation index at: https://developer.runa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> 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.

<Warning>
  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.
</Warning>

## Choosing a key

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.

## Responses when using idempotency

When using idempotency there are a number of cases you will need to cover.

* We will return the original response if a second request is made with the same key and body.
* We will return an `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.
* We will return an `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.

## Endpoints using idempotency

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](/reference/2024-02-05/endpoint/orders/create).
