Handle failures and retries at scale

At a few calls a day, failures are anecdotes. At tens of thousands, they are a distribution you have to manage. This page is the operational view; the diagnostic view is Calls fail or drop early.

Classify before you retry

Not every non-success is retryable.

Class	Statuses	Action
Retryable	`no-answer`, `busy`	Retry on a schedule — the contact exists and was unavailable
Sometimes retryable	`failed`, `error`, `stopped`	Retry once, then quarantine. Repeats point at a provider or number problem
Never retry	`balance-low`	Fix the wallet. Retrying burns the queue against a hard stop
Not a failure	`rescheduled`	Guardrails deferred the call to your allowed window
Completed but unsuccessful	`completed` with a negative outcome	A business problem, not a delivery problem — handle it in extractions and dispositions

Configure retries once, in the call

Set retry_config on the Make call API or the Create batch API rather than rebuilding retry logic in your own scheduler:

{
  "retry_config": {
    "enabled": true,
    "max_retries": 3,
    "retry_on_statuses": ["no-answer", "busy", "failed"],
    "retry_intervals_minutes": [30, 60, 120]
  }
}

Widening intervals is deliberate: three attempts inside ten minutes annoy the same unavailable person, while 30/60/120 minutes samples different parts of their day. See Retry calls that did not connect for every option, including prioritizing retries ahead of fresh contacts.

Retries consume concurrency and wallet balance like any other call. A campaign sized for 5,000 contacts with three retries each must be planned as up to 20,000 calls.

Respect the two limits that bite at scale

Concurrency

Your account has a floor and, optionally, a ceiling on simultaneous calls. Sub-accounts share one organization envelope, so one team’s campaign can starve another’s unless minimums are set.

Calling hours

Guardrails evaluate the recipient’s local time. A campaign spanning several countries will legitimately reschedule large portions of itself.

Also mind API rate limits when enqueuing: submit a batch rather than thousands of individual POST /call requests.

Monitor without polling everything

Take results from webhooks as the primary channel — Get results with webhooks — and poll only for executions you never heard about.
For a batch, read GET /batches/{batch_id}/executions rather than fetching each execution individually. It returns a bare array.
Treat only terminal statuses as final: completed, no-answer, busy, failed, canceled, stopped, error, balance-low.
Watch the mix, not the total. A rising share of failed in one country is a carrier incident; a rising share of no-answer across the board usually means the calling window drifted.

Before the next big campaign

Readiness checklist

Pre-launch verification

Control cost per call

Retries multiply spend

Call a contact list in bulk

How batches work

Build

Deploy

Monitor

Go live

Handle failures and retries at scale

Classify before you retry

Configure retries once, in the call

Respect the two limits that bite at scale

Concurrency

Calling hours

Monitor without polling everything

Before the next big campaign

Readiness checklist

Control cost per call

Call a contact list in bulk

​Classify before you retry

​Configure retries once, in the call

​Respect the two limits that bite at scale

Concurrency

Calling hours

​Monitor without polling everything

​Before the next big campaign

Readiness checklist

Control cost per call

Call a contact list in bulk

Classify before you retry

Configure retries once, in the call

Respect the two limits that bite at scale

Monitor without polling everything

Before the next big campaign