Skip to main content

​
Call statuses

Every call moves through these statuses:
StatusWhat it means
queuedCreated, waiting to go out
initiatedSent to the telephony provider
ringingPhone is ringing
in_progressSomeone answered, conversation is live
completedCall finished normally, results being processed
no_answerNobody picked up
busyLine was busy
canceledCanceled before connecting
failedSomething went wrong

​
Terminal statuses

Once a call hits one of these, it’s done:
  • completed — call succeeded
  • no_answer — nobody picked up
  • busy — line was busy
  • canceled — canceled before connecting
  • failed — error

​
Result statuses

After a call completes, extraction runs if you set a returns schema:
StatusWhat it means
pendingStill extracting
completedDone; data is in result
failedExtraction broke; reason is in result_error

​
Webhook statuses

If you set a webhook_url:
StatusWhat it means
pendingNot sent yet
deliveredYour server returned 2xx
failedAll retries failed; see webhook_error

​
HTTP error codes

CodeWhenWhat it means
201POST /v1/callsCall created
200GET /v1/calls, GET /v1/calls/{id}OK
400AnyBad request body or params
401AnyBad or missing API key
404GET /v1/calls/{id}Call not found (wrong ID or wrong org)
502POST /v1/callsTelephony provider couldn’t place the call

​
Error response format

Errors come back as JSON: 
{
  "error": "call a1b2c3d4-e5f6-7890-abcd-ef1234567890 not found"
}

​
Handling failures

Look at error_code, error_message, and hangup_cause on the call object. Common reasons: invalid phone number, telephony provider issue, not enough credits.
Check result_status and result_error. This usually happens when the transcript is empty (call ended before any conversation) or the model couldn’t parse what you asked for. Return fields come back as null in either case.
Check webhook_status and webhook_error. Common causes: your server returned a non-2xx code, the request timed out (10s limit), or the URL resolved to a private IP. You can always poll GET /v1/calls/{id} as a fallback.