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:
{ "status": "ok" }
A successful response with data:
{
"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:
{
"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.