Skip to content

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.

JSON
{
  "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.

ClassHTTPWhat it meansRetry?
Never accepted400 or 422DNC, a bad E.164 phone, a paused campaign, invalid consent, a missing external_idNo. Resell or fix.
Conflict409The same external_id in this campaign with a different phone or is_test, or this phone is already enrolled under another idNo. Use the existing status_url in details when we include one, which we do only for a lead your key can read.
Not found404LEAD_SOURCE_NOT_FOUND (the campaign is not in your organization) or LEAD_NOT_FOUNDNo. Check the id.
Idempotency in flight409The same Idempotency-Key is still writingYes, with the same key.
Rate limit429You are over a limitYes, after Retry-After, with the same key.
Temporary503Our DNC check could not run, or other posts for the same phone were being written at that momentYes, after Retry-After. No row was created.
Server error500Something failed mid-postYes, with the same external_id. We normally remove a lead that never enrolled. If one was left, the retry enrolls it or refuses it.
Auth401 or 403A bad key, or a partner key calling POST /callsNo.

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"
  }'

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-Key and body. The original response, unchanged. A create stays 201 with data.replayed=false, plus the header X-Idempotency-Replayed: true.
  • Same external_id only, with a new key or none. The original lead as 200 with data.replayed=true, the header X-Duplicate: external_id and the same status_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.

Updated Nov 7, 2026