Errors

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

{ "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:

{
  "error": "validation_error",
  "details": {
    "formErrors": [],
    "fieldErrors": { "prompt": ["Required"] }
  }
}

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

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.

Get started

Agents & sessions

Phones

Billing and limits

Validation errors

Common errors

Session failure codes

Retrying safely

​Validation errors

​Common errors

​Session failure codes

​Retrying safely

Validation errors

Common errors

Session failure codes

Retrying safely