Failover Statuses

This page describes flow-level and per-channel statuses for Standard and Transactional Failover (POST /failover and POST /failover/transactional). Both APIs share the same status model and tracking.

Failover OTP (POST /failover-otp/otp/send-failover) is a separate service with its own tracking API. It uses similar high-level outcomes (InProgress, Succeeded, Failed) — see Send a Failover OTP message.

Flow-level lifecycle

Queued → InProgress → Succeeded· final | Failed· final

Every Failover flow has one overall status in tracking, callbacks, and search. Values appear as Queued, InProgress, Succeeded, or Failed (PascalCase).

Status	Terminal?	Meaning
Queued	No	The flow was accepted and is waiting to start (first step not yet in progress).
InProgress	No	At least one step has been sent; the flow is waiting for a terminal channel status or for the next step after failover.
Succeeded· final	Yes	A step finished with a successful channel outcome. No further steps run.
Failed· final	Yes	The flow ended without success — all steps failed, no next step was available, balance error, or a terminal status was not in that step's `failoverOnStatuses`.

How the flow status is decided

When a channel reports a terminal status for the current step:

Successful outcome (Delivered, Seen on Viber; Delivered on SMS; Completed on Voice) → flow becomes Succeeded. Later steps are not sent.
Failure outcome and the status is in that step's failoverOnStatuses → the next step (by order) is sent; flow stays InProgress.
Failure outcome in failoverOnStatuses, but no next step → flow becomes Failed with statusCode "2".
Failure outcome not in failoverOnStatuses → flow becomes Failed with statusCode "3".
Send error starting the next step → flow becomes Failed with statusCode "1" (insufficient balance) or "0" (other error).

Examples

Viber → SMS: Viber Undelivered (in failoverOnStatuses) → SMS sent → SMS Delivered → Succeeded.
Viber only: Viber Delivered → Succeeded immediately (SMS never runs).
Viber → SMS: Viber Undelivered → SMS Undelivered → Failed (no more steps).
Viber → SMS: Viber Seen → Succeeded (Seen is successful; SMS is not attempted).

`statusCode` (when status is Failed)

When overall status is Failed, statusCode is a string with extra detail:

statusCode	Constant	When it is set
`"0"`	Server error	Sending the next step failed with a system error (not balance-related).
`"1"`	Insufficient balance	Sending the next step failed because of insufficient account balance.
`"2"`	No next step	A terminal status matched `failoverOnStatuses`, but the flow had no further step configured.
`"3"`	Status not a trigger	A terminal failure status was not listed in that step's `failoverOnStatuses`.

statusCode is only meaningful when status is Failed. It is not an HTTP status code.

`failoverOnStatuses` — defaults and allowed values

Channel	Default `failoverOnStatuses`	Allowed values in API (create)
Sms	`Failed`, `Undelivered`	`Failed`, `Undelivered`
Viber	`Expired`, `Failed`, `Undelivered`	`Expired`, `Failed`, `Undelivered`
Voice	`Busy`, `NoAnswer`	`Busy`, `NoAnswer`, `Failed`, `Unsent`, `Terminated`

Note: Terminal statuses such as SMS Unsent or Viber UNSENT are not accepted in failoverOnStatuses on create. If the provider returns them, the flow typically ends Failed with statusCode "3".

Successful channel outcomes (never trigger failover): Viber DELIVERED, SEEN; SMS Delivered; Voice Completed.

Viber message statuses

Tracking and callbacks use UPPERCASE Viber status names.

Status	Terminal?	Successful?	Typical effect on flow
QUEUED	No	—	Flow stays InProgress; message still processing.
DELIVERED· final	Yes	Yes	Flow Succeeded (no failover).
SEEN· final	Yes	Yes	Flow Succeeded (no failover).
UNDELIVERED· final	Yes	No	Failover if listed in `failoverOnStatuses` (default: yes).
EXPIRED· final	Yes	No	Failover if listed (default: yes).
FAILED· final	Yes	No	Failover if listed (default: yes).
UNSENT· final	Yes	No	Not allowed in `failoverOnStatuses` on create; usually Failed / `"3"`.

SMS message statuses

Tracking uses PascalCase SMS status names.

Queued → Sent → Delivered· final | Undelivered· final | Failed· final | Unsent· final

Status	Terminal?	Successful?	Typical effect on flow
Queued	No	—	Flow stays InProgress; message queued.
Sent	No	—	Flow stays InProgress; awaiting final DLR.
Delivered· final	Yes	Yes	Flow Succeeded.
Undelivered· final	Yes	No	Failover if listed (default: yes).
Failed· final	Yes	No	Failover if listed (default: yes).
Unsent· final	Yes	No	Not allowed in `failoverOnStatuses` on create; usually Failed / `"3"`.

Undelivered may include a detailedStatus in tracking under status.reason.

Voice message statuses

Tracking uses PascalCase Voice status names.

Status	Terminal?	Successful?	Typical effect on flow
Unknown	No	—	Call state not yet determined.
Queued	No	—	Call queued.
Initiated	No	—	Call initiated.
Ringing	No	—	Destination ringing.
InProgress	No	—	Call in progress (channel status, not flow status).
Completed· final	Yes	Yes	Call answered / completed → flow Succeeded.
Busy· final	Yes	No	Failover if listed (default: yes).
NoAnswer· final	Yes	No	Failover if listed (default: yes).
Failed· final	Yes	No	Failover if listed in `failoverOnStatuses`.
Unsent· final	Yes	No	Failover if listed (e.g. insufficient balance at send).
Terminated· final	Yes	No	Failover if listed (e.g. forced termination).

Multi-step example (Voice → Viber → SMS)

Voice (step 1)	Viber (step 2)	SMS (step 3)	Flow status
Completed· final	—	—	Succeeded· final — Voice success stops the flow
Busy· final	DELIVERED· final	—	Succeeded· final
Busy· final	UNDELIVERED· final	Delivered· final	Succeeded· final
Busy· final	UNDELIVERED· final	Undelivered· final	Failed· final
NoAnswer· final	UNDELIVERED· final	Failed· final	Failed· final

— = step not reached.

Tracking, search, and callbacks

Retrieve tracking: GET /failover/tracking/{trackingId} — flow status, optional statusCode, per-step message statuses.
Search: POST /failover/tracking — filter by flow status (Queued, InProgress, Succeeded, Failed; case-insensitive).
Transactional flows: Same fields; filter with flowKind: transactional. Callback payloads include flowKind (standard or transactional).

See Callbacks (Webhook) and Resource Overview.

👍
Related
Failover endpoints — which API to use · How to send a Failover message · How to send a transactional Failover message