Skip to main content
A network timeout tells you nothing about whether the request arrived. Without a way to say “this is the same request”, your only options are retrying and risking a double charge, or not retrying and losing the work. Send an Idempotency-Key, any unique string up to 255 characters (a UUID by convention):

​
Where it is required

POST /v1/calls, POST /v1/agents/{id}/test-call, POST /v1/phone-numbers/purchase and POST /v1/billing/topups. Omitting it returns 400 missing_idempotency_key. POST /v1/realtime/sessions honours the header if you send it; other endpoints ignore it. POST /v1/campaigns/{id}/start also spends money, and takes no key. A second start while the campaign is running is refused with 409 campaign_already_running, but starting it again after it has stopped or completed dials every lead again.

​
What happens on a retry

Replaying the same key with the same body returns the original response (same status, same body) with an extra header:
Keys are retained for 24 hours. After that the same key is a new request.

​
Two ways it can refuse

Generate a new key per logical operation, not per attempt. Retrying a failed call with a fresh key is a second call. Retrying it with the same key is the same call.