Errors and recovery

Axilio reports failures at four customer-visible layers:

API errors reject an HTTP request.
Phone-control errors occur over the Device Control Protocol.
Run failures happen after a workflow run was accepted.
Dashboard live-video errors affect the browser viewer separately from SDK or CLI control.

Identify the layer before retrying. A failed live-video connection, for example, does not necessarily mean the phone session or DCP control path failed.

API errors

HTTP failures use a Problem Details JSON body with a status and human-readable detail. Validation responses can also include field-specific errors.

Status	Meaning	Recovery
`400 Bad Request`	A business rule or input check failed.	Read the detail, correct the request, and do not retry it unchanged.
`401 Unauthorized`	The credential is missing, invalid, or expired.	Run `axilio login` or supply a valid organization-scoped API key.
`402 Payment Required`	Balance, plan, or quota state blocks the operation.	Read the detail, then correct the account requirement in Billing.
`403 Forbidden`	The caller lacks the required organization permission.	Select the correct organization or ask an administrator for access.
`404 Not Found`	The resource does not exist or is not visible to the organization.	Verify the ID and organization.
`408 Request Timeout`	The request exceeded a server or gateway deadline.	Retry with backoff only when the operation is safe to repeat.
`409 Conflict`	Current state conflicts with the request, such as a busy phone or duplicate active name.	Refresh the resource, resolve the conflict, and try again.
`422 Unprocessable Entity`	The body or query does not match the endpoint schema.	Correct the fields identified by the validation errors.
`429 Too Many Requests`	The caller exceeded a rate limit.	Honor retry guidance and back off.
`500 Internal Server Error`	Axilio encountered an unexpected failure.	Retry once with backoff; report it if it persists.
`502 Bad Gateway`	A phone or edge service rejected the operation.	Read the detail and correct the upstream condition.
`503 Service Unavailable`	A service is temporarily unavailable.	Retry with backoff.
`504 Gateway Timeout`	A phone or edge service missed its deadline.	Retry later; use a new session if the current one cannot recover.

CLI
Python SDK
Go SDK
REST API

The CLI writes errors to standard error and returns a stable exit status:

axilio runs get run_123
status=$?

case "$status" in
  0) echo "success" ;;
  2) echo "invalid command or request" ;;
  3) echo "authentication or permission failure" ;;
  4) echo "not found" ;;
  5) echo "timed out" ;;
  6) echo "service or phone unavailable" ;;
  7) echo "canceled" ;;
  *) echo "unclassified failure" ;;
esac

axilio runs get run_123

switch ($LASTEXITCODE) {
  0 { "success" }
  2 { "invalid command or request" }
  3 { "authentication or permission failure" }
  4 { "not found" }
  5 { "timed out" }
  6 { "service or phone unavailable" }
  7 { "canceled" }
  default { "unclassified failure" }
}

from axilio.platform import ApiError

try:
    run = client.runs.get("run_123")
except ApiError as error:
    print(error.status_code, error.body)
    if error.status_code in {429, 500, 503, 504}:
        print("retry with backoff when the operation is safe")
    else:
        raise

_, err := api.Runs.Get(ctx, &platformgo.RunsGetRequest{
    RunID: "run_123",
})
if err != nil {
    var apiErr *core.APIError
    if errors.As(err, &apiErr) {
        log.Printf("status=%d", apiErr.StatusCode)
    }
    return err
}

REST API References:

Get a run: GET /runs/{run_id}

Examples use Bash. To run them in PowerShell, see Run the curl examples on Windows.

curl --silent --show-error --fail-with-body --include \
  --url https://api.axilio.ai/api/v1/runs/run_123 \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY"

CLI exit statuses

Branch on the status rather than parsing human-readable error text.

Status	Meaning
`0`	Success.
`1`	Generic failure, including HTTP `402` and `409`.
`2`	Invalid syntax, arguments, values, or HTTP `400`/`422`.
`3`	Missing or rejected credentials, or HTTP `401`/`403`.
`4`	Resource or active allocation not found, or HTTP `404`.
`5`	Timeout, including HTTP `408` and an on-screen target that never appears.
`6`	Service or phone unavailable, rate-limited, or HTTP `429`/`5xx`.
`7`	Canceled by the user, shell, or system.

Phone-control errors

Python maps stable phone-control error codes to exception classes. Go returns *mobile.Error with Code, Message, and Retryable. The CLI maps them to the exit statuses above.

Code	Python exception	CLI exit	Meaning	Retryable by default
`unknown_op`	`UnknownOpError`	`1`	The executor does not recognize the operation.	No
`invalid_args`	`InvalidArgsError`	`2`	The command parameters are invalid.	No
`no_allocation`	`NoAllocationError`	`4`	No active allocation exists for the command.	No
`not_connected`	`NotConnectedError`	`6`	The executor cannot reach the phone agent.	No
`device_offline`	`DeviceOfflineError`	`6`	The phone is temporarily unavailable.	Yes
`unauthorized`	`UnauthorizedError`	`3`	The session credential was rejected.	No
`internal`	`InternalError`	`1`	The executor encountered an unclassified failure.	No
`canceled`	`CanceledError`	`7`	The operation context or deadline was canceled.	No
`connection`	`ConnectionError`	`6`	The control transport exhausted its bounded reconnect budget.	Yes
`session_ended`	`SessionEndedError`	`1`	The session ended or the connection was superseded.	No
`control_held`	`ControlHeldError`	`1`	Another controller holds the session’s control lease.	No
`timeout`	`TimeoutError`	`5`	A command exceeded its deadline.	Yes
`action_timeout`	`ActionTimeoutError`	`5`	A locator’s target never became actionable within its timeout. Also a built-in `TimeoutError` in Python.	No
`strategy_unavailable`	`StrategyUnavailableError`	`2`	The locator needs a resolver this session doesn’t have, such as the accessibility tree.	No

Prefer the retryable value carried by the actual error over a table default. The SDK transport automatically attempts bounded reconnect and cursor resume before it surfaces a connection error.

CLI
Python SDK
Go SDK

axilio phone find "the Continue button" --timeout 5s
status=$?

case "$status" in
  0) echo "found" ;;
  5) echo "observe again or refine the description" ;;
  6) echo "retry if the session is still active" ;;
  *) echo "inspect stderr" ;;
esac

axilio phone find "the Continue button" --timeout 5s

switch ($LASTEXITCODE) {
  0 { "found" }
  5 { "observe again or refine the description" }
  6 { "retry if the session is still active" }
  default { "inspect stderr" }
}

from axilio.drivers.mobile import ActionTimeoutError, AxilioError

with client.session("android", phone_id="ph_123") as driver:
    try:
        driver.locator(query="the Continue button").tap(timeout=5)
    except ActionTimeoutError:
        print("observe again or refine the description")
    except AxilioError as error:
        print(error.code, error.retryable, error.message)
        if not error.retryable:
            raise

_, err := driver.Locator(mobile.Query("the Continue button")).Tap(mobile.WithTimeout(5 * time.Second))
if err != nil {
    if mobile.IsActionTimeout(err) {
        log.Print("observe again or refine the description")
        return nil
    }
    var driverErr *mobile.Error
    if errors.As(err, &driverErr) {
        log.Printf("code=%s retryable=%t", driverErr.Code, driverErr.Retryable)
    }
    return err
}
return nil

For session_ended, create or select a live session. For control_held, close or coordinate with the existing controller instead of retrying against the one-controller guardrail. See Reconnect and resume for the transport contract.

Workflow-run failures

Creating a run can succeed while the run later fails waiting for a phone or executing workflow code. A successful fetch of a failed run still returns HTTP 200 and CLI exit status 0; branch on the run’s status field.

CLI
Python SDK
Go SDK
REST API

axilio runs get run_123 -o json

run = client.runs.get("run_123")
if run.status == "failed":
    print(run.error_message)

run, err := api.Runs.Get(ctx, &platformgo.RunsGetRequest{
    RunID: "run_123",
})
if err != nil {
    log.Fatal(err)
}
if run.GetStatus() == platformgo.RunResponseStatusFailed {
    if message := run.GetErrorMessage(); message != nil {
        log.Print(*message)
    }
}

REST API References:

Get a run: GET /runs/{run_id}

Examples use Bash. To run them in PowerShell, see Run the curl examples on Windows.

curl --silent --show-error --fail-with-body \
  --url https://api.axilio.ai/api/v1/runs/run_123 \
  --header "X-Axilio-Api-Key: $AXILIO_API_KEY"

Use error_message for the terminal reason. Inspect the run’s Telemetry and retained record for the execution sequence and output logs.

Dashboard live-video errors

The Dashboard can report that it could not reach the live phone, lost the connection, or reached the live-viewer limit. These messages describe the browser’s WebRTC video and input path, not the DCP connection used by the CLI and SDKs. After an established video connection drops, the Dashboard retries up to three times before presenting Reconnect. A viewer-limit message means another Dashboard or embedded viewer occupies the available slot; close one before reconnecting. The CLI and SDKs do not expose this Dashboard live-video state. If you already control the same session, test the independent DCP path:

CLI
Python SDK
Go SDK

axilio sessions current
axilio phone observe

screen = driver.observe()

screen, err := driver.Observe()
if err != nil {
    log.Fatal(err)
}
fmt.Println(screen.Hash)

If control succeeds, only the browser viewer needs recovery. If it fails, use the DCP error above. A session created only in the Dashboard is not automatically attached to a separate CLI process.

Report a persistent problem

Include the method or command, error status or code, affected resource IDs, approximate time, and whether the live-video path, control path, or both were affected. Do not share API keys, session credentials, control_url, telemetry_url, or live_view_url.

Next steps

Configuration

Configure credentials, retries, timeouts, and client state.

Session lifecycle

Understand session and connection deadlines.

Live view

Protect and recover the browser viewer.

Get Started

Phones and Sessions

Workflows and Runs

Files

Observability

Telemetry

Usage

Billing

Organization

Reference

Errors and recovery

API errors

CLI exit statuses

Phone-control errors

Workflow-run failures

Dashboard live-video errors

Report a persistent problem

Next steps

Configuration

Session lifecycle

Live view

​API errors

​CLI exit statuses

​Phone-control errors

​Workflow-run failures

​Dashboard live-video errors

​Report a persistent problem

​Next steps

Configuration

Session lifecycle

Live view

API errors

CLI exit statuses

Phone-control errors

Workflow-run failures

Dashboard live-video errors

Report a persistent problem

Next steps