> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getvoxai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getvoxai.com/_mcp/server.

# Idempotency

If a request that writes times out or the connection drops, you do not know whether it was carried out. The `Idempotency-Key` header lets you repeat it without the risk of doing the same thing twice.

## How it works

Generate a unique key for each operation and send it in the header:

```bash
curl -X POST https://api.getvoxai.com/v1/campaigns/CAMPAIGN_ID/pause \
  -H "Authorization: Bearer $VOXAI_API_KEY" \
  -H "Idempotency-Key: 6f1c2a9e-5b7d-4c0a-9e3f-2d8b1a4c7e90"
```

* The key has 16 to 64 characters: letters, digits, `-` and `_`. A UUID is fine.
* The key is valid for 24 hours.
* The scope of the key is (Organization, environment, key): two customers can use the same string, and a test key never meets a live key's.
* A malformed request does not use up the key.

## Which routes accept it

| Method                   | Header                                                          |
| ------------------------ | --------------------------------------------------------------- |
| `POST`                   | **Required.** Without it the response is `400 invalid_request`. |
| `PUT`, `PATCH`, `DELETE` | Optional. If present, it has the same effect.                   |
| `GET`                    | Ignored.                                                        |

The exception are searches that use `POST` only to carry a body: `POST /v1/knowledge/search`, `POST /v1/caller-requests/search` and `POST /v1/caller-requests/export` are reads. They take no key, store nothing and, if you send one, it is ignored.

## What happens when you repeat the request

With the same key and the same request you get the **same response** as the first time, with the header `Idempotent-Replayed: true`. The operation is not run again. Two kinds of response come back with some fields set to `null` (see below).

| Situation                                                                   | Response                                                                                    |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Same key, same request, first request finished                              | The stored response, with `Idempotent-Replayed: true`.                                      |
| Same key, same request, the first response held a secret or a delivery body | The stored response with those fields set to `null`, and a header that says so (see below). |
| Same key, different request                                                 | `422 idempotency_key_reused`.                                                               |
| Same key, first request still running                                       | `409 request_in_progress`, with `Retry-After`. Retry shortly with the same key.             |
| The first request failed because of a temporary error                       | See below.                                                                                  |

### Which responses are stored

* Deterministic errors (`4xx`, except `429` and the temporary `409`s) are stored and repeated as they are.
* When the operation itself fails with a `429`, a `5xx` or a temporary `409`, nothing is stored: for a retriable operation the key is released and a retry with the same key runs the operation again.
* A `429 rate_limited` from the request limit and `409 request_in_progress` come before the operation: they leave the key as it is, so retry with the same key.
* A response that shows a secret only once is stored without it: the replay of `POST /v1/webhook-endpoints` and `POST /v1/webhook-endpoints/{endpoint_id}/rotate-secret` has `secret: null` and the header `Idempotent-Replay-Secret-Omitted: true`. If you lost the first response, rotate the secret.
* The replay of `POST /v1/webhook-endpoints/{endpoint_id}/test` and `POST /v1/webhook-deliveries/{delivery_id}/resend` has `request_body` and `response_body_truncated` set to `null`, with the header `Idempotent-Replay-Body-Omitted: true`. Read the delivery with a GET if you need them.
* A stored response is kept up to 48 KiB of text. A longer one is replayed with the same HTTP status but with the body replaced by `{"troncata": true}` and the header `Idempotent-Replay-Truncated: true`: in that case read the state of the resource with a GET.

## Operations that are not retriable

For three operations a blind retry would cost or duplicate something:

* `POST /v1/calls` (starts a call);
* `POST /v1/campaigns` (creates a campaign);
* `POST /v1/knowledge/documents/{document_id}/reindex` (a new indexing).

The same holds for `POST /v1/webhook-endpoints` and `POST /v1/webhook-endpoints/{endpoint_id}/rotate-secret`, because they create a secret.

If one of these fails without a clear answer (the operation fails with a `429`, a `5xx` or a temporary `409`), the outcome is **uncertain**: the same key gets `409 idempotency_outcome_unknown` and the operation is never run again blindly. If the connection dropped with no response at all, the same key returns the first outcome or that same `409`. To get out of it:

1. **Read the state** of the resource, for example `GET /v1/outbound-calls/{outbound_call_id}` or the list of calls, `GET /v1/campaigns` for a campaign, `GET /v1/knowledge/documents/{document_id}` for a document.
2. Only if the operation did not happen, retry with a **new key**.

All the other writes are retriable: if they fail because of a temporary error, the same key runs them again.

### Outbound call with an uncertain outcome

If the telephony service does not answer with certainty, `POST /v1/calls` answers `202` with `status: "uncertain"` and `call_id: null`. Do not repeat the call: read its state with `GET /v1/outbound-calls/{outbound_call_id}`.

## Retry example

#### Node.js

```js
import { randomUUID } from "node:crypto";

const key = randomUUID(); // one per operation, reused across retries

async function pauseCampaign(campaignId) {
  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      const response = await fetch(
        `https://api.getvoxai.com/v1/campaigns/${campaignId}/pause`,
        {
          method: "POST",
          headers: {
            Authorization: `Bearer ${process.env.VOXAI_API_KEY}`,
            "Idempotency-Key": key,
          },
        },
      );
      if (response.status === 429 || response.status >= 500) {
        const wait = Number(response.headers.get("Retry-After") ?? 2);
        await new Promise((r) => setTimeout(r, wait * 1000));
        continue;
      }
      return await response.json();
    } catch {
      await new Promise((r) => setTimeout(r, 2000)); // connection dropped
    }
  }
  throw new Error("Operation failed: read the state before retrying");
}
```

#### Python

```python
import os
import time
import uuid
import requests

key = str(uuid.uuid4())  # one per operation, reused across retries

def pause_campaign(campaign_id: str):
    for _ in range(3):
        try:
            response = requests.post(
                f"https://api.getvoxai.com/v1/campaigns/{campaign_id}/pause",
                headers={
                    "Authorization": f"Bearer {os.environ['VOXAI_API_KEY']}",
                    "Idempotency-Key": key,
                },
                timeout=30,
            )
        except requests.RequestException:
            time.sleep(2)  # connection dropped
            continue
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 2)))
            continue
        return response.json()
    raise RuntimeError("Operation failed: read the state before retrying")
```

This pattern is for retriable operations. For the three that are not retriable, after an unclear error read the state first.

## Test keys

With a `vx_test_` key writes are simulated. Test idempotency keys are separate from live ones: the same string used in the two environments never meets.