Error codes

Every error has the same shape. Branch on code. It is a fixed word, and we never rename one without at least 6 months’ notice. message is written for people and can change.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone",
    "message": "phone: Phone number has too few digits (minimum 10)",
    "param": "phone",
    "request_id": "req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c"
  }
}

See Errors and retries for which ones to retry.

invalid_request

HTTP 400, type invalid_request_error. The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call.

Any endpoint can send it.

invalid_phone

HTTP 400, type invalid_request_error. The phone number is not a valid number.

Sent by: POST /campaigns/{campaignId}/leads, POST /dnc, GET /dnc/check, POST /leads.

on_dnc_list

HTTP 422, type invalid_request_error. The number is on the organization’s Do Not Call list.

Sent by: POST /calls, POST /campaigns/{campaignId}/leads, POST /leads.

outside_calling_hours

HTTP 422, type invalid_request_error. It is outside the lead’s calling hours.

Not sent today: a lead outside its calling hours is scheduled for the next window instead of refused.

duplicate_lead

HTTP 409, type invalid_request_error. A lead with this phone number (or external_id) already exists in this campaign. lead_id names it.

Sent by: POST /campaigns/{campaignId}/leads, POST /leads, PATCH /leads/{id}.

number_retired

HTTP 422, type invalid_request_error. The number was retired in this campaign after repeated failed calls.

Sent by: POST /calls, POST /campaigns/{campaignId}/leads, POST /leads.

consent_required

HTTP 422, type invalid_request_error. This campaign requires consent on every lead.

Sent by: POST /campaigns/{campaignId}/leads, POST /leads.

campaign_closed

HTTP 409, type invalid_request_error. The campaign is completed and takes no new leads.

Sent by: POST /calls, POST /campaigns/{campaignId}/leads, POST /leads.

queue_full

HTTP 429, type rate_limit_error. The campaign already has 5,000 API leads waiting to be called. Retry after Retry-After seconds.

Sent by: POST /campaigns/{campaignId}/leads, POST /leads.

test_flows_busy

HTTP 429, type rate_limit_error. Test mode only: this test key already has 20 sample calls running. Retry after Retry-After seconds.

Sent by: POST /calls, POST /campaigns/{campaignId}/leads, POST /leads.

phone_cannot_change

HTTP 422, type invalid_request_error. A lead’s phone number can’t be changed (Story 34-7). Add a new lead with the new number.

Sent by: PATCH /leads/{id}.

ambiguous_external_id

HTTP 409, type invalid_request_error. This external_id matches leads in more than one campaign. candidates lists them; add campaign_id (Story 34-7).

Sent by: GET /leads.

duplicate_dnc_entry

HTTP 409, type invalid_request_error. This number is already on the Do Not Call list.

Sent by: POST /dnc.

not_found

HTTP 404, type invalid_request_error. No such object or endpoint (or it belongs to someone else).

Any endpoint can send it.

authentication_failed

HTTP 401, type authentication_error. The key ID or secret is missing, wrong, revoked, expired or disabled.

Any endpoint can send it.

permission_denied

HTTP 403, type permission_error. The key is not allowed to do this.

Any endpoint can send it.

rate_limited

HTTP 429, type rate_limit_error. Too many requests a minute for this key or the organization’s plan. Retry after Retry-After seconds.

Any endpoint can send it.

too_many_concurrent_requests

HTTP 429, type rate_limit_error. Too many requests at the same time on this key. Retry after Retry-After seconds.

Any endpoint can send it.

lead_rate_limited

HTTP 429, type rate_limit_error. Too many new leads a minute on this key. Retry after Retry-After seconds.

Sent by: POST /campaigns/{campaignId}/leads, POST /campaigns/{campaignId}/leads/batch, POST /leads, POST /leads/batch.

idempotency_mismatch

HTTP 409, type idempotency_error. This Idempotency-Key was already used with a different request.

Any endpoint can send it.

idempotency_in_progress

HTTP 409, type idempotency_error. A request with this Idempotency-Key is still running. Retry after Retry-After seconds.

Any endpoint can send it.

limit_reached

HTTP 403, type invalid_request_error. A plan limit was reached (for example, webhook endpoints per organization).

Sent by: POST /webhook_endpoints, POST /webhooks.

endpoint_paused

HTTP 409, type invalid_request_error. The webhook endpoint is paused. Resume it (POST /webhook_endpoints/{id}/resume), then re-send or send the test event.

Sent by: POST /webhook_endpoints/{id}/deliveries/{delivery_id}/resend, POST /webhook_endpoints/{id}/test.

service_unavailable

HTTP 503, type api_error. A service we depend on is unavailable. Retry later.

Any endpoint can send it.

internal_error

HTTP 500, type api_error. Something went wrong on our side.

Any endpoint can send it.

lead_busy

HTTP 409, type invalid_request_error. The lead is being dialed or is on a call now.

Sent by: POST /calls.

lead_taken_out_of_queue

HTTP 409, type invalid_request_error. A person took the lead out of the dialing queue in CallView; the API does not overrule a person.

Sent by: POST /calls.

call_limit_reached

HTTP 429, type rate_limit_error. The lead has had 3 calls started by the API in the last 24 hours. Retry after Retry-After seconds.

Sent by: POST /calls, POST /leads.

number_not_allowed

HTTP 422, type invalid_request_error. A premium-rate or international number (including +1 Caribbean numbers) is not dialed for this organization. reason says which: premium or international.

Sent by: POST /calls, POST /campaigns/{campaignId}/leads, POST /leads.

recording_not_available

HTTP 404, type invalid_request_error. The call has no recording: recording is off for the organization, or it is past retention.

Sent by: GET /calls/{id}/recording.