Errors

Every failure uses the same shape: an error object with a stable code and a message meant for people.

{
  "error": {
    "code": "agent_not_found",
    "message": "no agent 'agent_missing' in this organisation"
  }
}

Branch on the HTTP status and the code. Do not parse the message: its wording can change.

Validation failures use 422 with the code invalid_request. The message names the field that failed, for example to_number: Value error, to_number must be E.164, e.g. +919876543210.

Errors any endpoint can return

Status	Code	Meaning
401	missing_api_key	No Authorization or X-API-Key header.
401	invalid_api_key	The key is malformed, unknown or revoked.
403	developer_api_disabled	The Developer API is not enabled for your organization.
402	entitlement_blocked	A write (any request that is not a GET) was refused because your plan cannot write right now.
404	voice_not_entitled	Your plan does not include AI voice calling.
404	voice_agents_disabled	AI voice agents are not available.
422	invalid_request	A body, path or query value failed validation. The message names the field.
429	rate_limited	Over the requests per minute limit. Wait Retry-After seconds.
503	service_unavailable	Temporarily unavailable. Retry shortly.

Endpoint errors

These codes come from specific endpoints. Each endpoint page lists the ones it can return.

Status	Code	Meaning
400	invalid_idempotency_key	The Idempotency-Key header must be 1 to 128 characters.
400	invalid_status	The status filter is not a known call status.
400	invalid_limit	limit is above the maximum for the list.
400	invalid_cursor	The cursor is not one this API issued.
402	insufficient_voice_minutes	The plan has no AI voice minutes, or none are available right now.
403	recording_private	The recording is private and cannot be linked.
404	agent_not_found	No such agent in your organization.
404	call_not_found	No such call in your organization.
404	campaign_not_found	No such campaign in your organization.
404	recording_not_found	The call has no recording yet.
409	archived	The agent is archived.
409	managed_by_sahay	The agent is managed by Sahay and cannot be edited through the API.
409	no_draft	The agent has no editable draft.
409	draft_moved	The draft changed while you were saving. Read it again and retry.
409	empty_instructions	Write the agent’s instructions before publishing.
409	nothing_to_rollback	There is no earlier published version.
409	murf_voice_required	The agent needs a Murf voice that speaks its languages.
409	murf_voice_cannot_speak	The chosen Murf voice does not speak the agent’s languages.
409	tts_provider_cannot_speak	The agent’s voice provider cannot speak one of its languages.
409	speech_provider_locked	Your organization cannot choose a voice provider for its agents.
409	agent_not_published	The agent must be active, custom and published.
409	no_caller_id	The agent has no number to call from.
409	agent_number_paused	The agent’s number is paused.
409	not_draft	Only a draft campaign can be changed.
409	bad_window	window_start must be before window_end.
409	no_contacts	A campaign needs at least one contact before it starts.
409	not_pausable	The campaign cannot be paused in its current status.
409	not_resumable	The campaign cannot be resumed in its current status.
409	not_stoppable	The campaign cannot be stopped in its current status.
409	tick_not_scheduled	The campaign dialer could not be scheduled. Try again.
422	number_not_callable	The number is blocklisted, opted out, or a Sahay voice number.
429	live_call_limit	Your organization already has its maximum number of calls in progress.
502	executor_unreachable	The voice service did not answer. The call may have rung.
502	executor_refused	The voice service refused the call.
503	lines_busy	All voice lines are busy. Retry after the Retry-After seconds.
503	voice_not_configured	Voice calling is not configured.
503	entitlement_check_failed	The plan’s AI voice minutes could not be checked. Try again.

Retrying

• Retry 429, 502 and 503 with a delay. Honor Retry-After when it is present.
• Do not retry 400, 402, 403, 404, 409 or 422 without changing the request.
• When retrying POST /calls, send the same Idempotency-Key so a call is never placed twice. See Calls.