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:
- 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
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).
Which responses are stored
- Deterministic errors (
4xx, except429and the temporary409s) are stored and repeated as they are. - When the operation itself fails with a
429, a5xxor a temporary409, 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_limitedfrom the request limit and409 request_in_progresscome 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-endpointsandPOST /v1/webhook-endpoints/{endpoint_id}/rotate-secrethassecret: nulland the headerIdempotent-Replay-Secret-Omitted: true. If you lost the first response, rotate the secret. - The replay of
POST /v1/webhook-endpoints/{endpoint_id}/testandPOST /v1/webhook-deliveries/{delivery_id}/resendhasrequest_bodyandresponse_body_truncatedset tonull, with the headerIdempotent-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 headerIdempotent-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:
- Read the state of the resource, for example
GET /v1/outbound-calls/{outbound_call_id}or the list of calls,GET /v1/campaignsfor a campaign,GET /v1/knowledge/documents/{document_id}for a document. - 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
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.