# Pearl REST API response format and error codes

Every Pearl REST API response is a JSON object containing a `status` field. Successful operations always return `"status": "ok"`, and endpoints that return data add a `result` field alongside it.

*Applies to: Pearl-2, Pearl Mini, Pearl Nexus, Pearl Nano.*

A successful response with no return value:

```json
{ "status": "ok" }
```

A successful response with data:

```json
{
  "status": "ok",
  "result": { "version": "4.24.5" }
}
```

**Error responses.** On failure, `status` is set to an error keyword and a `message` field carries a human-readable description:

```json
{
  "status": "notfound",
  "message": "Channel not found"
}
```

**Status keywords and HTTP codes.**

| HTTP code | `status` value | Meaning |
| --- | --- | --- |
| 200 | `ok` | Request succeeded |
| 201 | `ok` | Resource created (new publisher, new input, new ad-hoc event) |
| 400 | `badrequest` | Invalid or missing request parameters |
| 403 | `forbidden` | Operation is forbidden |
| 404 | `notfound` | Channel, publisher, input, output, recorder, storage, preset, or event does not exist |
| 405 | `notallowed` | Operation is not permitted for this object |
| 409 | `conflict` | Resource conflict, such as a limit being reached or an object being in the wrong state |
| 500 | `error` / `internalservererror` | Internal server error |
| 503 | `unavailable` | Service unavailable |

Check the `status` field rather than assuming success from an HTTP 200 alone, and log the `message` field when handling errors — it names the specific object that failed, for example `streamer '99' for channel '1' not found`.

> product: pearl-family · topic: other · source: pearl-rest-api.md · updated: Oct 7, 2026