# Errors

Status codes the API returns, what each one means and how to recover.

The API uses standard HTTP status codes. Failed requests come back as JSON with an `error` message you can show or log. Actions that report a result (start, stop, quality, custom voices) also include `"ok": false`.

```json
{
  "ok": false,
  "error": "No voice selected. Use POST /v1/voice first."
}
```

## Status codes

| Code | Meaning | What to do |
|---|---|---|
| `200` | The request worked. | Read the response body. |
| `400` | The body is invalid or the action failed, for example no voice is selected yet or a voice model couldn't be downloaded. | Fix the request, or follow the message. |
| `401` | The API key is missing or wrong. | Send `Authorization: Bearer <key>` with the key from **Settings > Developer**. |
| `403` | The account needs an active subscription for this, for example to create custom voices. | Subscribe in the app. |
| `404` | Unknown path, or no voice with that ID. | Check the path, or list voice IDs with `GET /v1/voices`. |
| `409` | Conflict, such as the custom voice limit being reached. | Delete a custom voice first, or contact support. |
| `503` | The desktop app isn't signed in. | Open Voices AI Live and sign in. |
| `504` | The app didn't finish in time (custom voices). | Keep the app open and signed in, then try again. |

## Can't connect at all

If the request never gets a response, the API isn't listening:

- Make sure Voices AI Live is open. The API stops when you quit the app.
- Check that **Stream Deck and other apps** is on in **Settings > General**.
- Use the endpoint shown in **Settings > Developer**. The default is `http://127.0.0.1:19470`.

## Messages you may see

- `No voice selected. Use POST /v1/voice first.`: select a voice before starting. See [Select a voice](/reference/set-voice).
- `Open the desktop app and sign in before using the local API.`: the app is open but signed out.
- `Invalid JSON body` or `Missing required field: …`: the request body doesn't match the reference for that endpoint.
