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

# Errors and status codes

> The status codes and error codes of the Core API v2, and what a failed call looks like in JSON and in plain text.

A failed call answers a status code and an error code. Match on the error code: it is a fixed string. The `message` is human text and can change.

<CodeGroup>
  ```json JSON theme={null}
  {"ok":false,"error":"not_found","message":"unknown signal 'nope'"}
  ```

  ```text Plain text theme={null}
  ERR not_found
  ```
</CodeGroup>

Some errors add fields before `ok`. A `station_mismatch` carries `expected` and `station`, see [Station safety](/develop-with-vra/core-control-api/station-safety). A refused output command carries `output_id`, `slot`, `action` and the player's `ack`. A refused camera command carries `camera`, `angle`, `action` and Camera Assist's `ack`.

## Status codes

| Status | Error code | When |
| - | - | - |
| `200` | | The read or action succeeded. An action that was already in effect also answers `200`. |
| `202` | | `?wait=0`: the action was accepted and not awaited. The body carries `"pending":true`. |
| `400` | `invalid_args` | A missing or wrong argument, like `/studio/set?value=maybe`, `/on` on a STRING signal or on a variable that is not BOOLEAN, a variable value that does not fit its type, or a camera or angle name that is not unique. |
| `401` | `unauthorized` | No valid token, legacy header or LAN access, or a revoked token, or a token with a fixed IP address used from another address. Comes with `WWW-Authenticate: Basic realm="VRASERVERCOREAPI"`. |
| `403` | `forbidden` | The device may not use this feature, a legacy header was sent to a `/api/v2` route, or a browser page on another site called the Core through loopback or LAN access. See [Authentication and LAN access](/develop-with-vra/core-control-api/authentication-and-lan-access). |
| `403` | `feature_disabled` | The feature, or the whole API, is switched off for the studio. |
| `403` | `read_only` | A read-only device called a control route, the signal is an `OUTPUT`, or the variable is not one the API may write. |
| `404` | `not_found` | Unknown signal, macro, automation, output, camera, angle or variable, a missing system signal, or the output player or Camera Assist does not know the target. |
| `409` | `station_mismatch` | Another station holds the studio. For a variable write the cloud can answer it too, when the studio switched station just before. |
| `409` | `station_changing` | The studio is switching station and the call names a station, by pin or by `?station=`. Handle it like `503`: retry in a moment. |
| `409` | `signal_disabled` | The signal is disabled. |
| `409` | `not_active` | The command was refused in the current state. Output players answer it when the scene is not on air, a limit rejects the command, or the scene is not a playout scene. The player's own code is in `ack.error`, see [Outputs](/develop-with-vra/core-control-api/routes#controlling-an-output). Camera commands answer it when the studio is off air or the Core is not `ACTIVE`, see [Cameras](/develop-with-vra/core-control-api/routes#controlling-a-camera). |
| `500` | `error` | The action failed inside the Core, or an output player or Camera Assist refused it for a reason the Core does not map. The message says why. |
| `503` | `not_ready` | The Core is starting, or the data is not loaded yet: signals, macros, automations, the schedule, cameras, variables. Also when signals are offline, when the Core has no MQTT connection for the outputs or variables, or when the cloud is unreachable for a variable write. |
| `504` | `timeout` | The action was sent but not confirmed in time, or no output player, Camera Assist or cloud answered. It may still apply. |

A path the Core does not know answers `404` with an empty body. A `POST` to a read route answers `405`.

## Retrying

* `503 not_ready` and `409 station_changing` are temporary. Retry after a second or two.
* `504 timeout` means the Core did not see the result in time. Read the state before you send the action again. With explicit routes like `/on` and `/onair` a second call is safe: an action that is already in effect does nothing.
* Every other error needs a change in the call or in the settings.

## Legacy routes

The [legacy routes](/develop-with-vra/core-control-api/legacy-routes) keep Core v1's bodies:

* `401` answers the text `Unauthorized`, with the same `WWW-Authenticate` header.
* `403` answers the text `Forbidden`.
* A refused control route answers the current state as text with the status of its error code, for example `503` while the Core starts.


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