Errors
Error reference
Branch on code, never on the message. Every code below says whether a retry can help and what to do next.
On this page
Error shape
A failed request returns a JSON body with one error object and the HTTP status that goes with the code.
codestringAlways presentmessagestringAlways presentparamstringMay be absentdetailsobject or nullMay be absentnext_attempt_local. It can be null, and some auth errors omit it.doc_urlstringMay be absentapi.entrovox.com/developer/docs address that redirects to the entry in a browser. Other errors omit it.request_idstringAlways presentAn error body
{
"error": {
"code": "DNC_BLOCKED",
"message": "The phone is on the Do Not Call list. No lead was created.",
"param": "phone",
"details": null,
"doc_url": "https://api.entrovox.com/developer/docs#dnc-blocked",
"request_id": "REQUEST_ID"
}
}What to do next
Each code carries one of four next steps. It tells you whether sending the same request again can ever work.
Don't retry
Retrying will fail the same way. Fix the request, or contact us.
Retry, same key
Safe to retry after Retry-After when present, otherwise back off. On a POST, resend the same Idempotency-Key and body.
Look up
The lead or request already exists. Fetch it instead of sending it again.
Retry later
Retry after the time in details.next_attempt_local when present. Otherwise retry when the blocking condition ends, as the meaning says.
Error codes
400
The phone is on the Do Not Call list. No lead was created.
Returned by
POST /v1/calls,POST /v1/leadsDon't retry
400
trustedform_cert_url is not a TrustedForm certificate URL. Entrovox checks the format only.
Don't retry
400
The campaign is paused. No lead was created. Retry only after we tell you the campaign is live.
Returned by
POST /v1/leadsDon't retry
400
The campaign is completed or not taking leads. A draft campaign accepts the lead and pauses it instead.
Returned by
POST /v1/leadsDon't retry
400
The owned and target lines of business are not a pair this cross-sell campaign quotes. No lead was created.
Don't retry
400 / 422
A field is missing or invalid, such as a bad E.164 phone or a missing external_id. param names the field.
Returned by
GET /v1/leads,POST /v1/leads,POST /v1/leads/batch,POST /v1/leads/ping,POST /v1/leads/{lead_id}/pauseDon't retry
400
from_number is not a phone number in your organization.
Returned by
POST /v1/callsDon't retry
400
The from number is not active, so it cannot place a call.
Returned by
POST /v1/callsDon't retry
400
The from number is quarantined. Use another number.
Returned by
POST /v1/callsDon't retry
400
The AI voice agent is not active.
Returned by
POST /v1/callsDon't retry
400
lead_id or lead_source_id does not belong to the enrollment named in the request.
Returned by
POST /v1/callsDon't retry
400
A recent call to this number has an unreviewed muted turn pending compliance review. Retry after the hold resolves.
Returned by
POST /v1/callsRetry later
400
The call cannot be placed now. details.reason says why. Retry later for outside_calling_hours, outside_transfer_hours_flag_off, org_holiday, the tcpa_* window reasons and same_phone_inflight: at details.next_attempt_local when present, otherwise when your agency's calling hours reopen, or after the current call to that number ends. Do not retry for org_calling_hours_invalid, org_invalid_timezone, tcpa_missing_timezone, tcpa_invalid_timezone or a cross-sell reason: fix your agency settings or the lead first.
Returned by
POST /v1/callsRetry later
401
The request has no API key.
Don't retry
401
The API key is not valid.
Don't retry
401
The API key has expired.
Don't retry
402
Your plan's included calls are used up. Enable extra calls in Billing.
Returned by
POST /v1/callsDon't retry
403
A read key tried to write. Use a key with write scope.
Don't retry
403
The endpoint is outside the partner surface, or the key's campaign binding is invalid. Ask for a new key.
Returned by
GET /v1/leads,GET /v1/leads/{lead_id},GET /v1/leads/{lead_id}/calls,POST /v1/leads,POST /v1/leads/batch,POST /v1/leads/ping,POST /v1/leads/{lead_id}/pause,POST /v1/leads/{lead_id}/resumeDon't retry
403
The body names a campaign other than the one this key is bound to.
Returned by
GET /v1/calls,GET /v1/leads,POST /v1/leads,POST /v1/leads/batch,POST /v1/leads/pingDon't retry
403
CALLS_NOT_ALLOWED_ON_BOUND_KEY
A partner key called POST /calls.
Returned by
POST /v1/callsDon't retry
404
No lead with that id in your organization.
Returned by
GET /v1/leads/{lead_id},GET /v1/leads/{lead_id}/calls,POST /v1/calls,POST /v1/leads,POST /v1/leads/{lead_id}/pause,POST /v1/leads/{lead_id}/resumeDon't retry
404
No call with that id in your organization.
Returned by
GET /v1/calls/{call_id},GET /v1/calls/{call_id}/analysis,GET /v1/calls/{call_id}/recording-url,GET /v1/calls/{call_id}/transcriptDon't retry
404
lead_source_id is not a campaign in your organization.
Returned by
POST /v1/calls,POST /v1/leads,POST /v1/leads/batch,POST /v1/leads/pingDon't retry
404
The call exists but its analysis is not written yet. It is pending until call.analysis.completed, or until analysis_status is completed.
Returned by
GET /v1/calls/{call_id}/analysisRetry later
404
The call has no recording, or its file is missing.
Returned by
GET /v1/calls/{call_id}/recording-urlDon't retry
404
The call has a recording that is still being processed. Retry after Retry-After, or wait for call.recording.ready (partner subscriptions, once webhook delivery is live).
Returned by
GET /v1/calls/{call_id}/recording-urlRetry later
404
No AI voice agent with that id in your organization.
Returned by
POST /v1/callsDon't retry
404
No phone number with that id in your organization.
Returned by
POST /v1/callsDon't retry
404
lead_source_lead_id is not a lead in one of your campaigns.
Returned by
POST /v1/callsDon't retry
404
The organization on this account was not found. Contact us.
Returned by
POST /v1/callsDon't retry
409
The same external_id exists in the campaign with a different phone or is_test.
Returned by
POST /v1/leadsLook up
409
A live lead with this phone is already enrolled under another external_id.
Returned by
POST /v1/leadsLook up
409
The same Idempotency-Key and path came with a different body.
Returned by
POST /v1/calls,POST /v1/leads,POST /v1/leads/batchDon't retry
409
A request with this Idempotency-Key is still being processed.
Returned by
POST /v1/calls,POST /v1/leads,POST /v1/leads/batchRetry, same key
409
The lead's sequence already ended, so it cannot be paused.
Returned by
POST /v1/leads/{lead_id}/pause,POST /v1/leads/{lead_id}/resumeDon't retry
409
Entrovox also runs this lead outside your campaign, so you cannot pause or resume it. Ask us.
Returned by
POST /v1/leads/{lead_id}/pause,POST /v1/leads/{lead_id}/resumeDon't retry
409
Your Entrovox contact, their integration or the system paused this lead. A campaign key cannot resume it. Ask us.
Returned by
POST /v1/leads/{lead_id}/resumeDon't retry
422
That filter is not available to API keys.
Returned by
GET /v1/leadsDon't retry
422
The lead is a test lead, so it cannot be called.
Returned by
POST /v1/callsDon't retry
422
The lead check blocked this lead, so no call was placed.
Returned by
POST /v1/callsDon't retry
429
The monthly AI minutes limit is reached. Unlike RATE_LIMIT_EXCEEDED, this 429 has no Retry-After and will not clear until the plan's minutes reset. Upgrade the plan or wait.
Returned by
POST /v1/callsDon't retry
429
Too many requests. Wait for Retry-After.
Retry, same key
500
Something failed on our side. Include request_id if you contact us.
Retry, same key
502
Billing is not set up for your account, so the call was not placed. Contact us.
Returned by
POST /v1/callsDon't retry
503
Our database is at capacity. A request with several writes may have saved some. Retry after Retry-After; retrying with the same key is safe.
Retry, same key
503
The recording could not be prepared as m4a. Retry after Retry-After, or use the Ogg recording.
Returned by
GET /v1/calls/{call_id}/recording-urlRetry, same key
Each row links to its own anchor. A doc_url is an api.entrovox.com/developer/docs#anchor link that redirects to this page and lands on that row in a browser. The last step needs JavaScript; a client without it ends on the API reference.