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

# Idempotency

> Retry a try-on or a batch safely: it runs once and is charged once.

A request can fail on the way back: a timeout, a dropped connection, a 502 from a proxy. You cannot tell whether the try-on was created, and sending it again could create and charge a second one.

Send an `Idempotency-Key` header and the retry is safe. The first request with a key runs. A repeat of the same request with the same key returns the first response and creates nothing new.

```bash theme={null}
curl -X POST "https://api.genlook.app/tryon/v1/try-on" \
  -H "x-api-key: gk_your_api_key" \
  -H "Idempotency-Key: 7f1c6c1e-3d0a-4c58-9d0e-8a1f1c2b3d4e" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [{ "externalId": "shirt-42" }],
    "person": { "image": { "source": { "id": "<imageId>" } } }
  }'
```

## Where it works

| Endpoint | With a key |
| - | - |
| [`POST /try-on`](https://docs.genlook.app/docs/tryon-api/endpoints/create-try-on) | A retry returns the same `generationId`. |
| [`POST /try-on/sync`](https://docs.genlook.app/docs/tryon-api/endpoints/create-try-on-sync) | A retry waits on the same generation and returns its result. |
| [`POST /batches`](https://docs.genlook.app/docs/tryon-api/endpoints/create-batch) | A retry returns the same batch. |

Other endpoints ignore the header. Reads, deletes, [`POST /products`](https://docs.genlook.app/docs/tryon-api/endpoints/create-product) and [cancelling a batch](https://docs.genlook.app/docs/tryon-api/endpoints/cancel-batch.md) are already safe to repeat.

## Rules

* **The key.** Any unique string of 1 to 255 ASCII characters. A UUID works, so does your own ID for the job, such as `order-1001-tryon`.
* **Kept 24 hours.** After that, the same key starts a new request.
* **Per account.** Two accounts can use the same key.
* **A replayed response** carries the header `Idempotency-Replayed: true`. It is the response of the first request: for `POST /try-on`, `status` is what it was at creation, so read the current one from [Generation Status](https://docs.genlook.app/docs/tryon-api/endpoints/generation-status.md).
* **A failed request frees its key.** If the first request returned an error, the retry runs again.

## Errors

| Code | HTTP | Meaning | What to do |
| - | - | - | - |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | The first request with this key is still running. | Retry after the `Retry-After` header (5 seconds). |
| `IDEMPOTENCY_KEY_REUSED` | 422 | The key was already used with a different body. | Use a new key for a new request. |
| `VALIDATION_FAILED` | 400 | The key is empty, over 255 characters or not ASCII. | Fix the key. |

## With the SDK

[`@genlook/api`](https://docs.genlook.app/docs/tryon-api/sdk) sends a fresh key with every `tryOn.create`, `tryOn.createSync` and `batches.create`, and reuses it on its own retries. Pass your own key to retry a call yourself later, from a queue or after a crash:

```ts theme={null}
await client.tryOn.create(input, { idempotencyKey: `order-${order.id}` });
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.