Skip to navigation

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:

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

MethodHeader
POSTRequired. Without it the response is 400 invalid_request.
PUT, PATCH, DELETEOptional. If present, it has the same effect.
GETIgnored.

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).

SituationResponse
Same key, same request, first request finishedThe stored response, with Idempotent-Replayed: true.
Same key, same request, the first response held a secret or a delivery bodyThe stored response with those fields set to null, and a header that says so (see below).
Same key, different request422 idempotency_key_reused.
Same key, first request still running409 request_in_progress, with Retry-After. Retry shortly with the same key.
The first request failed because of a temporary errorSee below.

Which responses are stored

  • Deterministic errors (4xx, except 429 and the temporary 409s) 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

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");
}

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.