Error Handling

Robust phone-agent integrations are not the ones that never fail - they are the ones that classify every failure correctly and know the recovery move. There are three error layers and nine terminal outcomes; this page gives the move for each.

Know which layer you’re in

Layer	You’ll see	It means
HTTP	`401`/`403` with a JSON body and `WWW-Authenticate` header	Authentication failed before MCP was reached. Fix credentials - see Authentication troubleshooting.
JSON-RPC	An `error` envelope with `error.data.reason`	The tool call was rejected: `device_paused`, `session_not_found_or_inactive`, `task_not_found`. Fix the call, not the task.
Task	A completed task whose payload has `terminal` and possibly an `error` object	The task ran and ended. Read `terminal` and act.

The task-level error object (holding error.control_type and error.prompt) is part of the task status payload - distinct from the JSON-RPC envelope.

A move for every terminal

Terminal	Recovery move
`ok`	Read `result`. Done.
`needs_user_control`	Not an error - a handoff. Get the user’s answer, send `phone_task_message`, monitor the `continuation_task_id`.
`timeout`	Retry with a higher `per_call_timeout_s` (max 900) or narrow the prompt. If a task keeps timing out, it is oversized - split it.
`queue_wait_exceeded`	The phone never started it. Check `phone_device_status` - online? paused? busy with an in-app task? Then start a new task, raising `queue_wait_timeout_s` if contention is normal.
`stopped_by_user`	Expected after cancels, session ends, and displacement by a newer task. Start a new task only if the work is still wanted.
`agent_error`	Retry once; inspect `error` for details. Repeated `agent_error` on the same prompt usually means the prompt needs disambiguation.
`device_offline`	Reconnect the device (Settings > Developer connection > Refresh in the AGI app), verify with `phone_device_status`, retry.
`session_expired`	Normal for long workflows. Start a new session and continue.
`iteration_limit`	The task was too big for the agent’s action budget. Split it into smaller tasks in one session.

Retry discipline

Retry the task, not blindly. timeout, agent_error, and device_offline are worth one retry after addressing the cause. Retrying iteration_limit without splitting, or queue_wait_exceeded without checking the device, just repeats the failure.
Never construct task IDs. Use exactly what phone_run_task returned; after a handoff, monitor the continuation_task_id, not the original. task_not_found usually means an expired or wrong-session ID - start a replacement task.
Cancellation races are benign. A cancel that arrives after completion returns already_completed: true; act on the task’s real terminal.
Repeating the same answer to a needs_user_control task is safe; sending a different second answer is rejected.

Design failure into the workflow

Split workflows into per-errand tasks so a failure only costs one step - see Task design.
Ask prompts to report “not found” explicitly, so an empty result is never ambiguous.
Treat monitor_timed_out: true as keep waiting, never as failure.

Task lifecycle

Where each terminal comes from

Troubleshooting

Symptom-based debugging

Getting Started

Core Concepts

Use Cases

Best Practices

Troubleshooting

Know which layer you’re in

A move for every terminal

Retry discipline

Design failure into the workflow

Task lifecycle

Troubleshooting

​Know which layer you’re in

​A move for every terminal

​Retry discipline

​Design failure into the workflow

​Related

Task lifecycle

Troubleshooting

Know which layer you’re in

A move for every terminal

Retry discipline

Design failure into the workflow

Related