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

# Idempotency key

> Prevent duplicate writes with X-Idempotency-Key on POST requests

## Why use it

Retries after a timeout or ambiguous `5xx` are common. Without an idempotency key, the server may treat each retry as a **new** request — duplicate tasks, extra credits, or duplicate webhooks.

`X-Idempotency-Key` marks one logical submission. Under your API Key, the same path + key is accepted only once within the TTL (default **24 hours**). **Retry the same intent with the same key**; start a new job with a **new key**.

<Info>
  Idempotency prevents **duplicate submissions**, not two different jobs.
</Info>

## What to send

Add the header on **every `POST` request** to the Open API (`/openapi/v1/**`):

```http theme={null}
X-Idempotency-Key: <unique-string>
```

Rules:

* Non-empty after trim, max length **64**
* Generate the key **before** the first attempt and keep it for safe retries
* Do not reuse a key for a different payload — you will get `409 Conflict`

## If the key was already used

* HTTP `409 Conflict`
* Header `Retry-After: 2`
* Body: `code: 409`, `message` contains `Idempotency key already used`

## Safe retry vs new work

| Situation                         | Key            |
| --------------------------------- | -------------- |
| First submit                      | New unique key |
| Retry after timeout (same intent) | **Same key**   |
| New task or new write             | **New key**    |

## Example

```bash theme={null}
export IDEM_KEY="job-$(date +%s)-$RANDOM"

curl -X POST "https://api.vmeg.ai/openapi/v1/task/tts/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Idempotency-Key: $IDEM_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json
```

<Tip>
  If the result is unclear, retry with the **same key**. Do not generate a new key on every retry, or you risk duplicate writes.
</Tip>