Errors and retries

Every error has the same shape, from every endpoint:

{
  "error": {
    "type": "invalid_request_error",
    "code": "duplicate_lead",
    "message": "A lead with this external_id already exists in this campaign.",
    "param": "external_id",
    "request_id": "req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c",
    "lead_id": "2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10"
  }
}

• code is a fixed word. Write your code against it. Error codes lists every one.
• message is for people. It can change, so don’t match on it. Phone numbers and emails in it are partly hidden.
• param names the field the error is about, when there is one.
• reason sometimes adds the exact cause, for example why a key was refused.
• request_id matches the Request-Id header. Quote it when you ask us for help: open a ticket from Help in the CallView app.

Retry, or fix?

What you got	What to do
429 (rate_limited, too_many_concurrent_requests, lead_rate_limited, queue_full, call_limit_reached, test_flows_busy)	Wait the number of seconds in Retry-After, then send the same request again.
409 idempotency_in_progress	Your first request with this Idempotency-Key is still running. Wait Retry-After and send it again.
500 internal_error, 503 service_unavailable, or no answer at all	Retry with the same Idempotency-Key, waiting longer each time (1 s, 2 s, 4 s and so on). The key makes sure nothing happens twice.
Any other 4xx	Sending it again gets the same answer. Fix the request, or record the refusal.

Some refusals are answers, not mistakes. duplicate_lead tells you that you already sent this lead, and on_dnc_list that the person asked not to be called. Record them in your CRM and move on.

Common ones

Code	Usually means
authentication_failed	Wrong key ID or secret, a revoked or expired key, or a secret that was rolled. reason says which.
permission_denied	The key can’t do this, or can’t use this campaign. The message says what’s missing.
invalid_request	A field is missing, unknown or the wrong type. param names it. Unknown fields are refused, so a typo like phon is caught.
invalid_phone	Not a US or Canadian number.
not_found	No such object, or it belongs to a campaign the key can’t use. We don’t say which.
duplicate_lead	Already in this campaign. lead_id is the lead you have.

Bodies over 1 MB, and broken JSON, get 400 invalid_request.