Errors

Most API errors return JSON with an error string. Some include a machine-readable code or additional state. Do not assume every error has a code.

{
  "error": "active session limit reached",
  "code": "session_limit",
  "session_limit": 2,
  "active_session_count": 2,
  "available_session_slots": 0
}

The numbers above are illustrative; inspect the actual response.

HTTP status	Common reason	Handling
`400`	Invalid JSON, timeout, arguments, or unsupported operation	Fix the request; check `unsupported` and the session’s `ops`.
`401`	Missing, invalid, or revoked bearer key; wrong credential kind	Check authentication.
`403`	Account lacks beta access, rentals are paused, or balance is insufficient	Read the error; contact support or obtain credit as appropriate.
`404`	Session does not exist, has left the live runtime, or belongs to another account	Recover your receipt/history if it was your session.
`409`	Not ready, closing, account capacity full, or idempotency conflict	Handle the specific reason; do not blindly start another phone.
`410`	A create key already completed, or a legacy transport is retired	Use a new key for an intentional new session, or the supported endpoint.
`500`	An unexpected service failure	Inspect current state and retry only when safe.
`503`	All phones are in use (`phones_busy`), recorded runtime unavailable, or no snapshot available yet	For `phones_busy` nothing was created: wait `retry_after_seconds` (also sent as `Retry-After`) and create again. Otherwise recover the receipt or retry a read after a delay.

Startup failure versus operation failure

A creation request may receive 202 and fail later. Watch state and error while provisioning; do not equate HTTP acceptance with a working phone. Once a phone is ready, an operation error is a separate result. It does not automatically mean a new phone is required. Check the session state, current app, or screen before deciding what to do next.

Creation replay responses

Response	Meaning
`202`	The original session is returned. It may still be provisioning or closing.
`409`, `idempotency_conflict`	This key was already used with a different request body.
`410`, `create_request_completed`	That session has completed cleanup. Use a new key only when you intend to create another phone.
`503`, `create_request_recorded`	Admission was recorded, but the runtime is currently unavailable. Preserve the returned ID and recover the receipt; do not assume nothing was created.
`503`, `phones_busy`	Every phone is in use. Nothing was created and nothing is billed. Wait `retry_after_seconds` (also the `Retry-After` header) and send the same request again; the same idempotency key is fine.

The receipt remains available after the live session is removed. state: "recorded" is a receipt state, not API readiness. state: "released" and cleanup_complete: true confirm completed cleanup.

Useful codes

beta_access_required: authenticated account is not allowed into the beta.
session_limit: account capacity is full.
idempotency_conflict: a create key was reused with different content.
create_request_completed: the original session has finished cleanup.
create_request_recorded: creation was recorded but the runtime cannot currently be read.
install_unknown: the install may have completed; inspect before retrying.

For support, include the session ID, create request key if used, approximate time, HTTP status, and public error. Leave out API keys, viewer URLs, screenshots containing private data, and app credentials.

Get started

Guides

Endpoints

Use cases

Startup failure versus operation failure

Creation replay responses

Useful codes

​Startup failure versus operation failure

​Creation replay responses

​Useful codes

Startup failure versus operation failure

Creation replay responses

Useful codes