> ## Documentation Index
> Fetch the complete documentation index at: https://phone-harness.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Handle authentication, startup, capacity, and operation errors separately.

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`.

```json theme={null}
{
  "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.

## 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.