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

# Idempotency

> How to safely repeat a creation using Idempotency-Key.

If the network drops after sending, you do not know whether the pre-test was created. Repeating the call without protection could create and charge twice. The `Idempotency-Key` header solves this.

## Rules

* The header is **required** on `POST /pretests`. Without it, the response is [`idempotency_key_required`](https://docs.myunite.ai/en/errors#idempotency_key_required).
* The value has 1 to 255 visible ASCII characters (no spaces). A value outside that responds [`invalid_request`](https://docs.myunite.ai/en/errors#invalid_request).
* The scope is the workspace: the same key in two workspaces is two different creations.
* **Same key and same body**: the API returns the same pre-test, with `202`, and the `Idempotent-Replayed: true` header. Nothing is created or charged again.
* **Same key and different body**: the response is `409` [`idempotency_conflict`](https://docs.myunite.ai/en/errors#idempotency_conflict).
* **Key of a pre-test that was deleted**: the response is `409` [`idempotency_key_retired`](https://docs.myunite.ai/en/errors#idempotency_key_retired). Use another key.

Generate a new value for each pre-test (a UUID works) and store it with your own record before sending. To repeat, reuse exactly the same value and the same body.

```bash curl theme={null}
curl -i -X POST https://myunite.ai/api/v1/pretests \
  -H "Authorization: Bearer $UNITE_API_KEY" \
  -H "Idempotency-Key: 6f0c2b1e-summer-urban-clock" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadId": "upl_0123456789abcdef0123456789abcdef.png",
    "title": "Summer · urban clock",
    "channel": "ooh",
    "ooh": { "format": "CATALOG_FORMAT" }
  }'
```

```javascript JavaScript theme={null}
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // store before sending

async function createPretest() {
  return fetch("https://myunite.ai/api/v1/pretests", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.UNITE_API_KEY}`,
      "Idempotency-Key": idempotencyKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      uploadId: "upl_0123456789abcdef0123456789abcdef.png",
      title: "Summer · urban clock",
      channel: "ooh",
      ooh: { format: "CATALOG_FORMAT" },
    }),
  });
}

const first = await createPretest();
// If the connection drops and you do not know the outcome, repeat with the same key:
const again = await createPretest();
console.log(again.headers.get("Idempotent-Replayed")); // "true" if it already existed
```

```python Python theme={null}
import os
import uuid
import requests

idempotency_key = str(uuid.uuid4())  # store before sending

def create_pretest():
    return requests.post(
        "https://myunite.ai/api/v1/pretests",
        headers={
            "Authorization": f"Bearer {os.environ['UNITE_API_KEY']}",
            "Idempotency-Key": idempotency_key,
        },
        json={
            "uploadId": "upl_0123456789abcdef0123456789abcdef.png",
            "title": "Summer · urban clock",
            "channel": "ooh",
            "ooh": {"format": "CATALOG_FORMAT"},
        },
    )

first = create_pretest()
# If the connection drops and you do not know the outcome, repeat with the same key:
again = create_pretest()
print(again.headers.get("Idempotent-Replayed"))  # "true" if it already existed
```

## 5xx error and timeout on creation

A `5xx` response (or a timeout) on `POST /pretests` does not prove nothing was created: the pre-test may have been created before the failure. **Always repeat with the same `Idempotency-Key`** and the same body. With the same key, the API returns the already-created pre-test, if there is one, or attempts the creation again. A new key may create, and charge for, a second pre-test.

## Quota failure

If creation fails with [`quota_exhausted`](https://docs.myunite.ai/en/errors#quota_exhausted) and the balance is later restored, repeating the same `Idempotency-Key` with the same body attempts the creation again and may use one quota unit. This is expected: the first attempt consumed nothing.

## The body counts

To compare a repeated call, Unite considers `uploadId`, `title`, `brandId`, the channel and its fields. If you want to change any of them, use a new key.

The `metadata` field does **not** count: repeating the call with different `metadata` does not cause a conflict, and the returned pre-test keeps the `metadata` of the first call. An empty `metadata` (`{}`) is the same as omitting the field.

A repeat with the same body returns the same pre-test even if, after the first call, the brand was renamed or the uploaded file was removed.


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