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

# Idempotency

> Retry decision requests without creating duplicates.

Send an `Idempotency-Key` header on `POST /v1/decisions` to make retries safe.
The header is optional, and the key must be 1 to 256 characters.

## How it behaves

| You send | What happens |
| - | - |
| A new key | A new request is created. |
| A key you already used, with the same input | You get the same operation back. No new work starts. |
| A key you already used, with different input | `409` `idempotency_conflict`. |
| No key | Every submission creates a new request, even for identical input. |

Keys are scoped to the account. Changing the `model` between `tazo-large` and
`tazo-small` under the same key counts as different input.

## Retry rules

**1. Generate one key per operation**

Create the key before your retry loop, not inside it.

**2. Reuse it for every attempt**

Send the same key and the same input on each retry.

**3. Use a new key for new work**

A different operation gets a different key.

```python theme={null}
import uuid, httpx

key = str(uuid.uuid4())          # once per operation

for attempt in range(4):
    response = httpx.post(
        "https://api.tazolabs.com/v1/decisions",
        headers={"Authorization": f"Bearer {api_key}", "Idempotency-Key": key},
        data={"request": request_json},
        files={"audio": open("request.wav", "rb")},
        timeout=60,
    )
    if response.status_code != 504 and response.status_code != 503:
        break
```

If you resume an earlier operation later, let callers supply the key you
retained for it.

## Pending results

If processing outlasts the wait, you get `504` with the code `decision_pending`,
an `X-Tazo-Request-Id` header, and a `request_id` in the body. Processing
continues in the background.

Check `error.retryable` before you retry:

* With a key, it is `true`. Repeat the POST with the same key to get the result.
* Without a key, it is `false`. Retrying would create a second request.

## Uncertain submissions

A `503` `durable_execution_unavailable` means the API could not confirm the
submission. The work may already have been accepted. With a key, retrying is
safe. Without one, retrying can create another request, so the API does not
recommend it.


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