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

# Errors

> How Lusor reports errors, and what to do about the common ones.

Errors are JSON with a machine-readable `error` code and a human-readable `message`:

```json theme={null}
{ "error": "not_found", "message": "Agent '…' not found" }
```

Branch on `error`, not on `message`. Messages can change. Some errors add fields, such as `currentSessionId` on `device_busy`.

## Validation errors

A request that fails validation returns `400` in one of two shapes, depending on the endpoint:

```json validation_error theme={null}
{
  "error": "validation_error",
  "details": {
    "formErrors": [],
    "fieldErrors": { "prompt": ["Required"] }
  }
}
```

```json bad_request theme={null}
{
  "error": "bad_request",
  "message": "Required"
}
```

* `validation_error` carries per-field `details`. Direct phone control actions and sessions started without an agent use this shape.
* `bad_request` carries one `message`. Agent endpoints, follow-up messages and answers to the agent use this shape.

Handle both: check `error`, then read `details` or `message`.

## Common errors

| Status | `error` | Meaning | What to do |
| - | - | - | - |
| `400` | `bad_request`, `validation_error` | The request is invalid. | Fix the request. See above. |
| `401` | `unauthenticated` | No API key was sent. | Send the key. See [Authentication](https://docs.lusor.ai/authentication.md). |
| `401` | `invalid_api_key` | The key is wrong or revoked. | Check the key, or create a new one. |
| `402` | `credits_exhausted` | Out of credits, or out of Lusor Phone minutes. | Add credits or turn on Overages. See [Credits and minutes](https://docs.lusor.ai/billing/credits-and-minutes.md). |
| `402` | `billing_required` | The Lusor Phone is not covered by an active paid plan. | Check your Phone plan in **Settings → Billing**. |
| `402` | `upgrade_required` | The session is older than your plan's history window. | Upgrade to read older history. |
| `403` | `forbidden` | The key may not do this. | Use the Lusor app for this action. |
| `403` | `secure_ask_dashboard_only` | The agent asked for a password or code. | Answer in the Lusor app. See [Answer the agent](https://docs.lusor.ai/agents/answer-the-agent.md#passwords-and-codes). |
| `404` | `not_found` | The resource does not exist, or belongs to another workspace. | Check the id and the key's workspace. |
| `409` | `device_releasing` | The phone is being removed from your Phone plan. | Use another phone. |
| `409` | `internet_route_inactive` | The Lusor Phone's internet connection is not active yet. | Try again once it is. |
| `410` | `stale_hitl_request` | The question you answered is no longer open. | Read the session's newest events. |
| `429` | `device_busy` | The phone is working on another session. | Wait for `currentSessionId` to finish, or stop it. |
| `429` | `rate_limit_exceeded` | Too many requests. | Wait `Retry-After` seconds. See [Rate limits](https://docs.lusor.ai/billing/rate-limits.md). |
| `500` | `internal_error`, `db_error` | Something went wrong on Lusor's side. | Retry shortly. |
| `502` | `upstream_error` | The phone or a Lusor service could not be reached. | Retry shortly. |
| `502` | `dispatch_outcome_unknown` | Lusor could not confirm whether your request was accepted. | Retry with the same `Idempotency-Key`. |
| `503` | `meter_unavailable` | Metering for the Lusor Phone could not start, so the action was not sent. | Retry shortly. |
| `503` | `history_policy_unresolved` | Your plan could not be read right now. | Retry shortly. |

A resource in another workspace returns the same `404` as one that does not exist, so a `404` never reveals another workspace's data.

## Session failure codes

A session that fails has status `failed` and a code in its `error` field. See [Follow a session](https://docs.lusor.ai/agents/follow-a-session.md#failure-codes).

## Retrying safely

Requests that start work (turns, sessions, follow-up messages) accept an `Idempotency-Key` header. Retry them with the same key, and Lusor returns the original result instead of doing the work twice. Reads are always safe to retry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.