Skip to content

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 present
A stable identifier. Branch on this.
messagestringAlways present
A sentence for a person. It can change, so do not match on it.
paramstringMay be absent
The field that failed, when one did.
detailsobject or nullMay be absent
Extra data some codes add, such as next_attempt_local. It can be null, and some auth errors omit it.
doc_urlstringMay be absent
Present on partner lead-surface errors and on API-key validation errors; it links to the code's entry in the error reference, by way of an api.entrovox.com/developer/docs address that redirects to the entry in a browser. Other errors omit it.
request_idstringAlways present
Quote it when you contact us.

An error body

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

Filter by HTTP status
  • 400

    DNC_BLOCKED

    The phone is on the Do Not Call list. No lead was created.

    Returned by POST /v1/calls, POST /v1/leads

    Don't retry

  • 400

    SOURCE_PAUSED

    The campaign is paused. No lead was created. Retry only after we tell you the campaign is live.

    Returned by POST /v1/leads

    Don't retry

  • 400

    SOURCE_INACTIVE

    The campaign is completed or not taking leads. A draft campaign accepts the lead and pauses it instead.

    Returned by POST /v1/leads

    Don't retry

  • 400

    CROSS_SELL_PAIR_INVALID

    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

    VALIDATION_ERROR

    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}/pause

    Don't retry

  • 400

    FROM_NUMBER_NOT_FOUND

    from_number is not a phone number in your organization.

    Returned by POST /v1/calls

    Don't retry

  • 400

    FROM_NUMBER_NOT_ACTIVE

    The from number is not active, so it cannot place a call.

    Returned by POST /v1/calls

    Don't retry

  • 400

    FROM_NUMBER_QUARANTINED

    The from number is quarantined. Use another number.

    Returned by POST /v1/calls

    Don't retry

  • 400

    AGENT_NOT_ACTIVE

    The AI voice agent is not active.

    Returned by POST /v1/calls

    Don't retry

  • 400

    LEAD_REFERENCE_MISMATCH

    lead_id or lead_source_id does not belong to the enrollment named in the request.

    Returned by POST /v1/calls

    Don't retry

  • 400

    MUTED_TURN_HOLD

    A recent call to this number has an unreviewed muted turn pending compliance review. Retry after the hold resolves.

    Returned by POST /v1/calls

    Retry later

  • 400

    DIAL_BLOCKED

    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/calls

    Retry later

  • 401

    AUTHENTICATION_REQUIRED

    The request has no API key.

    Don't retry

  • 401

    TOKEN_INVALID

    The API key is not valid.

    Don't retry

  • 401

    API_KEY_EXPIRED

    The API key has expired.

    Don't retry

  • 402

    CALL_QUOTA_EXCEEDED

    Your plan's included calls are used up. Enable extra calls in Billing.

    Returned by POST /v1/calls

    Don't retry

  • 403

    INSUFFICIENT_SCOPE

    A read key tried to write. Use a key with write scope.

    Don't retry

  • 403

    API_KEY_ENDPOINT_NOT_ALLOWED

    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}/resume

    Don't retry

  • 403

    LEAD_SOURCE_NOT_ALLOWED

    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/ping

    Don't retry

  • 403

    CALLS_NOT_ALLOWED_ON_BOUND_KEY

    A partner key called POST /calls.

    Returned by POST /v1/calls

    Don't retry

  • 404

    LEAD_NOT_FOUND

    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}/resume

    Don't retry

  • 404

    CALL_NOT_FOUND

    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}/transcript

    Don't retry

  • 404

    LEAD_SOURCE_NOT_FOUND

    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/ping

    Don't retry

  • 404

    CALL_ANALYSIS_NOT_FOUND

    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}/analysis

    Retry later

  • 404

    RECORDING_NOT_FOUND

    The call has no recording, or its file is missing.

    Returned by GET /v1/calls/{call_id}/recording-url

    Don't retry

  • 404

    RECORDING_NOT_READY

    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-url

    Retry later

  • 404

    VOICE_AGENT_NOT_FOUND

    No AI voice agent with that id in your organization.

    Returned by POST /v1/calls

    Don't retry

  • 404

    PHONE_NUMBER_NOT_FOUND

    No phone number with that id in your organization.

    Returned by POST /v1/calls

    Don't retry

  • 404

    LEAD_SOURCE_LEAD_NOT_FOUND

    lead_source_lead_id is not a lead in one of your campaigns.

    Returned by POST /v1/calls

    Don't retry

  • 404

    ORGANIZATION_NOT_FOUND

    The organization on this account was not found. Contact us.

    Returned by POST /v1/calls

    Don't retry

  • 409

    EXTERNAL_ID_CONFLICT

    The same external_id exists in the campaign with a different phone or is_test.

    Returned by POST /v1/leads

    Look up

  • 409

    LEAD_PHONE_CONFLICT

    A live lead with this phone is already enrolled under another external_id.

    Returned by POST /v1/leads

    Look up

  • 409

    IDEMPOTENCY_KEY_REUSED

    The same Idempotency-Key and path came with a different body.

    Returned by POST /v1/calls, POST /v1/leads, POST /v1/leads/batch

    Don't retry

  • 409

    IDEMPOTENCY_IN_PROGRESS

    A request with this Idempotency-Key is still being processed.

    Returned by POST /v1/calls, POST /v1/leads, POST /v1/leads/batch

    Retry, same key

  • 409

    LEAD_NOT_PAUSEABLE

    The lead's sequence already ended, so it cannot be paused.

    Returned by POST /v1/leads/{lead_id}/pause, POST /v1/leads/{lead_id}/resume

    Don't retry

  • 409

    LEAD_ENROLLED_ELSEWHERE

    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}/resume

    Don't retry

  • 409

    LEAD_PAUSED_BY_AGENCY

    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}/resume

    Don't retry

  • 422

    UNSUPPORTED_FILTER

    That filter is not available to API keys.

    Returned by GET /v1/leads

    Don't retry

  • 422

    LEAD_IS_TEST

    The lead is a test lead, so it cannot be called.

    Returned by POST /v1/calls

    Don't retry

  • 422

    LEAD_SCREENED_OUT

    The lead check blocked this lead, so no call was placed.

    Returned by POST /v1/calls

    Don't retry

  • 429

    AI_MINUTES_EXHAUSTED

    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/calls

    Don't retry

  • 429

    RATE_LIMIT_EXCEEDED

    Too many requests. Wait for Retry-After.

    Retry, same key

  • 500

    INTERNAL_ERROR

    Something failed on our side. Include request_id if you contact us.

    Retry, same key

  • 502

    UPSTREAM_ERROR

    Billing is not set up for your account, so the call was not placed. Contact us.

    Returned by POST /v1/calls

    Don't retry

  • 503

    DB_ADMISSION_OVERLOADED

    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

    DB_ADMISSION_UNAVAILABLE

    Our database is temporarily unavailable. Retry after Retry-After.

    Retry, same key

  • 503

    DB_BACKEND_UNAVAILABLE

    Our database did not answer. Retry after Retry-After.

    Retry, same key

  • 503

    PROVIDER_UNAVAILABLE

    Our DNC check could not run, or other posts for the same phone were being written at that moment. No lead was created. On a batch result row, resend only the failed rows in a new batch with a fresh Idempotency-Key; the external_id keeps it idempotent.

    Returned by POST /v1/leads, POST /v1/leads/ping

    Retry, same key

  • 503

    RECORDING_UNAVAILABLE

    The recording exists but a signed link could not be made right now. Retry after Retry-After.

    Returned by GET /v1/calls/{call_id}/recording-url

    Retry, same key

  • 503

    RECORDING_TRANSCODE_FAILED

    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-url

    Retry, 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.