Skip to main content

Responses and errors

DisplayNet API operations and SDVoE API operations use the same response envelope as the TCI API. A single parser can handle replies from all three interfaces. The HTTP status code describes how the request was handled; the envelope's status describes the operation.

POST /api/displaynet/preset_get response
{
  "status": "SUCCESS",
  "request_id": null,
  "result": { },
  "error": null
}
FieldDescription
statusSUCCESS, ERROR, or PROCESSING
request_idnull for DisplayNet API operations. SDVoE API operations may return an ID for an operation that is still being processed
resultThe command's payload, or null
errorAn object when status is ERROR, otherwise null

The values above apply to normal REST operation responses. A REST WebSocket can also carry notification messages with other status values; see Requests and Events.

Errors​

On failure, error is an object with a message and a reason.

Error response​

{
  "status": "ERROR",
  "request_id": null,
  "result": null,
  "error": {
    "message": "Unknown op 'version' (see GET /api/commands for available ops)",
    "reason": "UNKNOWN_OP"
  }
}

The message is for people. The reason is for code. Branch on reason, not on the message text, which may change.

Status codes​

CodeMeaning
200The request was handled synchronously; inspect the envelope for the operation result
201An SDVoE API operation was accepted for asynchronous processing; use the Location header to poll its result
400The request was malformed, or the command reported an error
401A token is required and was missing, invalid, or expired
403The request is forbidden, such as an operation against a locked target
404An SDVoE path was not recognized by the Control Server
502The Control Server could not be reached
503The DisplayNet engine connection is unavailable
Status code on command failure

A command that reports an error, such as a preset that does not exist or a missing parameter, returns 400. It does not return 200 with an error body. Check the status code first, then read error for the cause.

Asynchronous responses​

Some SDVoE API operations are accepted before the Control Server has finished processing them. The REST layer returns 201 Created and a Location header:

201 Created response​

HTTP/1.1 201 Created
Location: /api/request/23874

Poll that URL with GET. The response can remain PROCESSING until the operation finishes, then changes to SUCCESS or ERROR.

Error reasons​

Reasons fall into two groups.

Transport reasons are fixed. They come from the REST layer itself.

ReasonCause
UNKNOWN_OPNo such operation. See API Discovery
ILLEGAL_ARGUMENTThe body was not valid JSON, a required field was missing, or the URL and body named different operations
AUTH_FAILEDLogin credentials were rejected
AUTH ERRORA valid token was required and not supplied
DEVICE_LOCKEDThe target device is locked
ENGINE_UNAVAILABLEThe REST layer could not reach the DisplayNet engine
CONTROL_SERVER_UNREACHABLEThe Control Server could not be reached

Command reasons come from the command that reports them. For example, preset errors use PRESET API ERROR. Treat these reasons as categories rather than an enumerated list; other commands can return their own reasons.

A command-level error​

{
  "status": "ERROR",
  "request_id": null,
  "result": null,
  "error": {
    "message": "Missing required parameter 'name'",
    "reason": "PRESET API ERROR"
  }
}

Multiple responses​

A few commands emit several responses. The body is then a JSON array of envelopes rather than a single envelope.

A client that always expects an object will break on these responses. Check whether the parsed body is an array before reading status.

Notifications​

A command may also produce notifications. Notifications are separate from the command response and arrive on a WebSocket, not in the HTTP reply. See Requests and Events.

See also​