Go to production
Safe retries and idempotency
Which errors to retry, which to resell, and how external_id and Idempotency-Key keep a retry from starting a second sequence.
On this page
Two things make a retry safe: your external_id and an Idempotency-Key. Send the same external_id and the same Idempotency-Key on a retry and we will not start a second sequence.
Errors you can branch on
Every error is an envelope with a stable code. Branch on code, not on the sentence.
{
"error": {
"code": "DNC_BLOCKED",
"message": "Phone is on the DNC list, so we did not create a lead. Remove it from your list or pause it; do not retry.",
"param": "phone",
"doc_url": "…",
"request_id": "…"
}
}param is the JSON field that failed, when there is one. When present, doc_url is a link to that code's entry in the error reference. The link goes through the older api.entrovox.com/developer/docs address, which redirects to the entry in a browser. The last step needs JavaScript, so a script that follows redirects ends on the reference home instead.
| Class | HTTP | What it means | Retry? |
|---|---|---|---|
| Never accepted | 400 or 422 | DNC, a bad E.164 phone, a paused campaign, invalid consent, a missing external_id | No. Resell or fix. |
| Conflict | 409 | The same external_id in this campaign with a different phone or is_test, or this phone is already enrolled under another id | No. Use the existing status_url in details when we include one, which we do only for a lead your key can read. |
| Not found | 404 | LEAD_SOURCE_NOT_FOUND (the campaign is not in your organization) or LEAD_NOT_FOUND | No. Check the id. |
| Idempotency in flight | 409 | The same Idempotency-Key is still writing | Yes, with the same key. |
| Rate limit | 429 | You are over a limit | Yes, after Retry-After, with the same key. |
| Temporary | 503 | Our DNC check could not run, or other posts for the same phone were being written at that moment | Yes, after Retry-After. No row was created. |
| Server error | 500 | Something failed mid-post | Yes, with the same external_id. We normally remove a lead that never enrolled. If one was left, the retry enrolls it or refuses it. |
| Auth | 401 or 403 | A bad key, or a partner key calling POST /calls | No. |
Retry a post
Generate one Idempotency-Key per logical request and reuse it on every retry, including after a timeout or a dropped connection. The server may already have accepted the lead before the connection failed, and the same key makes the retry safe. In cURL, --retry-all-errors needs curl 7.71 or newer. Do not add --fail: without it an HTTP 4xx or 5xx is not a curl error, so only transport failures are resent and a 409 or 422 is never blindly retried.
# Generate the key once, then reuse it on every retry of this request.
# Same key, same body: a retry returns the original response.
IDEMPOTENCY_KEY=$(uuidgen)
curl --retry 5 --retry-all-errors --retry-max-time 60 --max-time 15 -X POST https://api.entrovox.com/v1/leads \
-H "Authorization: ApiKey $ENTROVOX_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d '{
"first_name": "Jordan",
"last_name": "Lee",
"phone": "+14255551234",
"external_id": "px-88421"
}'import os, time, uuid, requests
key = str(uuid.uuid4()) # one key per logical request, reused on every retry
body = {"first_name": "Jordan", "last_name": "Lee", "phone": "+14255551234", "external_id": "px-88421"}
r = None
for attempt in range(5):
try:
r = requests.post(
"https://api.entrovox.com/v1/leads",
headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}", "Idempotency-Key": key},
json=body,
timeout=15,
)
except (requests.exceptions.ConnectionError, requests.exceptions.Timeout):
time.sleep(2**attempt) # the lead may already be accepted; the same key makes the retry safe
continue
code = None
if r.status_code == 409: # only a 409 needs its body read; a 5xx may not be JSON
try:
code = r.json()["error"]["code"]
except ValueError:
pass
if r.status_code in (429, 503) or r.status_code >= 500 or code == "IDEMPOTENCY_IN_PROGRESS":
time.sleep(int(r.headers.get("Retry-After", 2**attempt)))
continue
break # success, or a final answer you must not retry
if r is None:
raise SystemExit("no response after 5 attempts")
print(r.status_code, r.headers.get("X-Idempotency-Replayed"))import { randomUUID } from "node:crypto";
const key = randomUUID(); // one key per logical request, reused on every retry
const body = JSON.stringify({ first_name: "Jordan", last_name: "Lee", phone: "+14255551234", external_id: "px-88421" });
let res;
for (let attempt = 0; attempt < 5; attempt++) {
try {
const signal = AbortSignal.timeout(15000);
res = await fetch("https://api.entrovox.com/v1/leads", {
method: "POST",
headers: {
Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`,
"Idempotency-Key": key,
"Content-Type": "application/json",
},
body,
signal,
});
} catch (err) {
// Network error or timeout. The lead may already be accepted; the same key makes the retry safe.
res = undefined;
await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
continue;
}
// Only a 409 needs its body read; a 5xx may not be JSON.
let code = null;
if (res.status === 409) code = (await res.clone().json().catch(() => ({}))).error?.code;
if (res.status === 429 || res.status === 503 || res.status >= 500 || code === "IDEMPOTENCY_IN_PROGRESS") {
const wait = Number(res.headers.get("Retry-After") ?? 2 ** attempt);
await new Promise((r) => setTimeout(r, wait * 1000));
continue;
}
break; // success, or a final answer you must not retry
}
if (!res) throw new Error("no response after 5 attempts");
console.log(res.status, res.headers.get("X-Idempotency-Replayed"));What a replay returns
This section covers lead posts. POST /calls follows the same rule: the same key and body replays the original call, and a different body or another API key answers 409 IDEMPOTENCY_KEY_REUSED, as described in Place a call.
What you get back depends on which identifier matched.
- Same
Idempotency-Keyand body. The original response, unchanged. A create stays201withdata.replayed=false, plus the headerX-Idempotency-Replayed: true. - Same
external_idonly, with a new key or none. The original lead as200withdata.replayed=true, the headerX-Duplicate: external_idand the samestatus_url.
An Idempotency-Key belongs to one path: the same key on POST /leads and on POST /leads/batch is two separate requests. The same key on this path with a different body, or a key already used by another API key, answers 409 IDEMPOTENCY_KEY_REUSED. Send a fresh UUID per request. The key is a transport-retry guard. external_id is the durable identity.
Two posts for one phone at the same moment
If two of your servers post the same phone together, one gets 201. The other gets 409 LEAD_PHONE_CONFLICT pointing at the lead that won, or a 503 to retry if it could not be decided in time. If your agency allows duplicate phones, both are accepted.
Count a lead once
Count a lead once per external_id, not once per 201. A retry of a lead that never finished enrolling can still be refused, as 400 DNC_BLOCKED or 409 LEAD_PHONE_CONFLICT, if its phone went DNC or into another live sequence in the meantime. No row is kept in that case.
Next steps
See Rate limits and volume for the Retry-After you will honor, and the go-live checklist before you turn volume on.