FleetDeckDocs

Operate

Errors and recovery

HTTP, driver and client errors use different status channels. Preserve action identity before deciding whether to retry.

Error shape

json
{
  "error": "Human-readable message",
  "code": "VALIDATION",
  "status": 422,
  "issues": [
    {
      "path": [
        "command",
        "x"
      ],
      "message": "Number must be less than or equal to 1"
    }
  ]
}

CLI exceptions write this shape to stderr. Client-only errors omit status; issues and retryAfterSeconds are optional. A terminal action failure stays in the action record on stdout with exit 1. MCP tool failures use a JSON text block with isError: true. Failed action records keep their driver error under result; validation rejected by the MCP SDK may instead be a plain-text tool error. Always inspect the envelope before parsing content.

MCP protocol errors

Transport and JSON-RPC failures happen before a FleetDeck tool result exists. JSON-RPC uses an error object with a numeric code and message; these are separate from the string codes below. FleetDeck checks authentication, origin and body limits first, so those failures use its HTTP error envelope.

Code / statusMeaningRecovery
-32700Invalid JSON-RPC message. Malformed raw JSON on the HTTP route is intercepted as INVALID_JSON instead.Send a valid JSON-RPC 2.0 request with id, method and valid params; use an MCP SDK.
-32600Invalid request or invalid/oversized initialization batch.Initialize separately and send individual well-formed calls.
-32601Method not found.Use initialize, ping, tools/list and tools/call supported by this tools server; do not assume resources or prompts exist.
-32602Invalid method or tool parameters. Unknown tool names can include this code inside plain-text isError content.Refresh tools/list and match the exact schema. Some SDK tool validation errors are isError text results instead.
-32603Unexpected JSON-RPC handler failure.Keep the request and action identifiers, inspect the original action and report nonsecret context.
-32000 / HTTP 400 or 406SDK transport refusal, unsupported protocol version, unacceptable Accept header, or a closed client connection.Use both accepted media types and the SDK-negotiated MCP-Protocol-Version. Reconnect for transport loss; query an existing action before retrying input.
-32001Client request timeout; the transport can also use this code with HTTP 404 for a closed session.Read the HTTP status and message, reconnect if needed, and inspect the original action before any repeat mutation.
HTTP 405 / 415Wrong HTTP method or content type.Use POST with application/json. GET/SSE subscriptions and DELETE sessions are not offered at /api/mcp.

An authentication failure can be HTTP 401 before initialization. HTTP 403 can indicate origin or scope refusal; HTTP 413 means the body exceeded 3 MB. Proxy HTML, connection resets and non-JSON gateway errors require transport recovery and are not successful tool results.

Codes and fixes

CONNECTION_FAILEDClient only

The client could not reach the configured FleetDeck origin.

Fix: Check DNS, TLS, proxy/firewall and FLEETDECK_BASE_URL. Before replaying a mutation, query its saved requestId when connectivity returns.

INVALID_RESPONSEClient only

The server response was not valid FleetDeck JSON.

Fix: Check that the base URL points to FleetDeck and that a proxy did not replace the response. Preserve the original action identifiers before retrying.

USAGECLI only

Unknown command or incorrect positional argument count.

Fix: Run fleetdeck --help and pass credentials through the environment, not command arguments.

ACTION_INCOMPLETEClient only

A convenience command expected completed action content but the action ended without it.

Fix: Read the original action status and result, then inspect the phone. Do not blindly resubmit the physical action.

CLIENT_ERRORClient only

A local parse, file, validation or runtime error occurred before a usable API response.

Fix: Correct the local input or filesystem problem. For uncertain network timing, recover by requestId before sending new input.

API_ERRORClient fallback

The client received an API failure without a usable FleetDeck code.

Fix: Record the nonsecret HTTP status and response context. Check the endpoint and service health before retrying a mutation.

INVALID_JSON400

Missing or malformed JSON.

Fix: Use valid JSON. Body-less routes should omit the body; required routes need their documented object.

INVALID_TIME400

Schedule is in the past or at/after a configured key expiry.

Fix: Choose a future instant with the correct UTC offset, before key expiry if set. A no-expiry key has no key-expiry cutoff; job deadlines and leases still apply.

UNAUTHORIZED401

Missing, malformed, expired or revoked credential; user verification/password state can also deny access.

Fix: Use Authorization: Bearer with a valid scoped key. For dashboard routes, sign in. Job children require an active parent job and timely renewal.

PLAN_REQUIRED402

Device account has no active entitlement.

Fix: Restore an active device entitlement in the workspace before controlling it.

FORBIDDEN403

Required scope, device grant, account membership or worker identity is missing.

Fix: Check the endpoint’s scopes, exact device, owning key and workerId. A different key cannot access the original key’s sessions or jobs.

ORIGIN403

Dashboard mutation lacks an allowed Origin header.

Fix: Use the signed-in same-origin dashboard. Cross-origin key management is not supported.

NOT_FOUND404

Unknown route or resource unavailable to this caller.

Fix: Check method/path and use returned IDs from this account/key. Do not guess IDs.

DEVICE_OFFLINE409

The phone is not connected, so a sequence cannot start.

Fix: Bring the phone online (agent app running, network up), then retry with the same requestId.

MODEL_MISMATCH409

The saved sequence was recorded on a different phone model.

Fix: Use a sequence recorded on this phone model; coordinates do not transfer between models.

SCHEDULE_CONFLICT409

The touch scheduler refused the change in the schedule’s current state (for example resuming is needed first, or the occurrence already ran).

Fix: Read the message, list the schedules again and apply the change that matches the current state.

INVALID_SCHEDULE400

The schedule time, cron, timezone, failure email or saved sequence was rejected by the touch scheduler (a foreign failure email returns HTTP 422 with this code).

Fix: Use five numeric cron fields or a runAt 30 seconds to one year ahead, a valid IANA timezone, a workspace member email and a sequence saved on this phone.

DEVICE_BUSY409

Another automation session, touch run or in-flight action owns the phone.

Fix: Wait for its release/expiry and any running lease. Coordinate operators; do not create parallel controls.

SESSION_EXPIRED409

Session expired, was closed or belongs to another key.

Fix: Read the original action if needed, acquire a new session and inspect before new input. Heartbeat before the returned expiresAt; temporary child keys can have much shorter sessions than 120 seconds.

IDEMPOTENCY_CONFLICT409

requestId already identifies a different command.

Fix: Retrieve that original action. Reuse its exact command only for lookup/retry; use a new ID only for a newly intended action.

ACTION_BUSY409

This session has queued or running work.

Fix: Poll the existing action to a terminal state before issuing another.

BRIDGE_BUSY409

Another authorized bridge was seen for this device within 15 seconds.

Fix: Stop the duplicate bridge or wait until the previous registration is stale. Keep worker IDs stable.

LEASE_EXPIRED409

Completion report no longer owns a live action/job lease.

Fix: Do not rerun the work. Inspect action/job status and the device; record the uncertainty in agent evidence.

LIMIT409

Maximum 50 active keys per user or 100 queued jobs per key.

Fix: Revoke unused keys or cancel unnecessary queued jobs before creating more.

REVOKE_FIRST409

Purge attempted on a key that is not revoked.

Fix: Revoke the key first, then purge only if permanent record deletion is intended.

WORK_ACTIVE409

Purge would delete an active action/job lease.

Fix: Wait for work and leases to finish, then retry purge. Do not erase active work history.

TOO_LARGE413

Request body exceeds its byte limit.

Fix: Keep /api/v1 bodies at or below 3,000,000 bytes and key creation at or below 16,384. Use media_chunk for large files.

CONTENT_TYPE415

A supplied JSON body lacks application/json content type.

Fix: Set Content-Type: application/json; charset parameters are accepted.

VALIDATION422

A field, type, bound or unknown property failed validation.

Fix: Read issues[].path and issues[].message. Match the endpoint schema; strict objects reject extra fields.

RATE_LIMIT429

At most 120 new actions per session in a rolling minute.

Fix: Pause until the window clears. Poll existing actions instead of resubmitting new work. No Retry-After header is currently supplied.

INTERNAL500

Unexpected service error.

Fix: Save nonsecret request context and time for support. Query action status before repeating a mutation; never assume it did not execute.

SCHEDULER_OFFLINE503

FleetDeck’s touch scheduler has not checked in recently, so a sequence run would not start.

Fix: Retry later with the same requestId.

UNAVAILABLE503

Touch schedules are not configured on this server.

Fix: Use the hosted FleetDeck API or configure the touch scheduler service.

UNSUPPORTEDAction result (driver 422)

Tool or parameter is unavailable on this transport, OS or phone-agent version.

Fix: Recheck capabilities and driver limitations. Connect a suitable private native bridge or update the phone agent; verify actual hardware support.

UNSUPPORTED_TEXTNative driver 422

ADB input cannot encode the requested text.

Fix: Use ASCII without literal %s, or a compatible relay/IME/native extension. The bridge stores UNSUPPORTED_TEXT as failed with its code; inspect the action result.

MEDIA_IMPORT_FAILEDAction result (driver 422)

Phone rejected Photos/gallery import.

Fix: Check complete file bytes, MIME, supported agent version and Photos/gallery permission. Inspect the gallery before retrying.

DEVICE_UNAVAILABLEAction result (driver 502/503/504)

Phone or relay could not provide the requested operation.

Fix: Check online state, capture/USB trust and relay connectivity. Wake/unlock locally if required; inspect state before repeating input.

DELIVERY_UNKNOWNAction result (driver 502/504)

Delivery may have happened but its outcome is unconfirmed.

Fix: Read the original action, then capture/inspect the phone. Do not blindly replay taps, uploads or publication.

CONFIGURATIONAction result (driver 503)

Server relay transport configuration is invalid.

Fix: Have the operator repair the relay URL; changing phone credentials will not correct server configuration.

NATIVE_FAILEDNative driver 502/504

Native ADB/MCP execution failed or exceeded its deadline.

Fix: Check ADB trust/serial or the native MCP service and connection. Inspect first; the command may already have had effects. The bridge preserves this code in an unknown action result.

WDA_FAILEDNative driver 502/504

WDA rejected or timed out on an operation.

Fix: Check WDA signing, running session and connectivity. A later action can re-establish a lost WDA session; inspect before new input. The bridge preserves this code in an unknown action result.

Action recovery

  1. Persist the session ID, requestId and exact command before submitting. Only action submission has request-ID idempotency; session acquisition and job creation do not.
  2. After an HTTP timeout, read GET /sessions/{sessionId}/actions/{requestId}. queued/running means poll, not send another physical action. An identical action POST returns the existing record while the session remains valid.
  3. completed means the driver finished. Relay input normally returns result.status=submitted and verified=false; native input may say applied and verified=false. Take a fresh screenshot or inspect to verify the app effect.
  4. failed means the attempt reported failure; it does not universally prove no side effects. unknown means effect cannot be established. Observe the phone before deciding whether a new action is safe. cancelled means queued work was cancelled; do not assume a previous running effect was undone.
  5. Expired running action leases become unknown and are never automatically replayed. Expired job leases become interrupted. Retained action metadata can outlive its result, which is cleared after one hour on subsequent service activity.
  6. Release the session in your client’s finally/cleanup path. Do not overlap manual control, another automation tool or another worker with the same phone.