REST API — responses and errors
Getting started describes access configuration, the address, and the header containing the key.
Check the HTTP code and the command result
The HTTP code, such as 200 or 401, describes request handling. The result of the command itself may be in the status field of the JSON response, a text data format. Read the response body as well: HTTP 200 can accompany a rejected command, such as invalid_variable or invalid_scene_num.
Lists and value reads do not have to contain a status field. An array of names, an empty array [], or a value object can be a valid result for the relevant method. A missing status is not an error on its own.
Common situations and actions
| HTTP | Situation | What to do |
|---|---|---|
401 |
Missing key, incorrect header format, disabled REST API, or an invalid key. Usually {"error":"invalid_access_token"}. |
Check the confirmed REST API state, current key, and Authorization: Bearer API_KEY header. Update the integration after replacing the key. |
403 |
Loopback source address; the response is {"error":"access_denied"}, even with a valid key. |
Connect the integration directly to the installation's address over the network. Do not use 127.0.0.1 or ::1. |
400 |
Invalid scene parameters or an invalid list format in a batch operation. | Check the parameters and body of the relevant method. Do not assume that every missing parameter in every method produces 400. |
404 |
Unknown object_id when reading a device. |
Retrieve the current device list and copy the identifier exactly from its response. Do not apply this rule to an unknown variable or scene. |
413 |
The body exceeds the 1 MiB limit. |
Reduce the request body. When splitting a batch write into smaller requests, account for the lack of a transaction. |
500 |
A processing error or a communication error with the automation server. Waiting for a response is limited to about 5 seconds. | Check installation availability and the error body. Before repeating a command, account for possible execution despite losing the response. |
308 |
With HTTPS active, an HTTP request without the HTTP exception enabled receives the target HTTPS address. | Use the HTTPS address from the Location header and a certificate trusted by the client. Getting started explains the HTTP option. |
200 with rejection in status |
The request was handled, but the command returned, for example, invalid_variable or invalid_scene_num. |
Check the variable name or the scene number and whether the scene exists. Do not record this response as a successful command. |
An unknown variable in a single read usually returns HTTP 200 with invalid_variable. A nonexistent scene can return HTTP 200 with invalid_scene_num. Both cases differ from HTTP 404 for an unknown device.
Example response forms
There is no single universal error format. A response may contain error, the status and message fields, or a form specific to the method. The examples below show the complete JSON bodies of individual responses.
Rejected access:
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
{"error":"invalid_access_token"}
Example of a general error response; here, status is a number corresponding to the HTTP code:
HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
{"status":500,"message":"Something went wrong"}
A rejected variable read despite HTTP 200; here, status is the textual operation result:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"status":"invalid_variable"}
Example response to starting a nonexistent scene:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"logic_action":"on_scene","status":"invalid_scene_num"}
Field names and protocol messages keep their form regardless of the guide's language. Do not base handling of every error solely on one field or one message.
Timeouts, lost responses, and retries
A timeout means that waiting for a response exceeded the time limit. A timeout, a broken connection, or a lost response does not prove that an operation was not executed. The server does not automatically resend a command that has been sent.
A read can be retried manually after the cause of the error has been resolved. Before repeating a command that changes state, check the available installation state and consider its effects:
- A batch variable write is not a transaction and does not roll back earlier changes. It may have been partially executed, and an error may end the entire request without a partial result. The waiting limit of about 5 seconds applies to the complete set of responses, not to each item separately.
- Starting a scene again may repeat its actions and renew deadlines. Losing a response is no basis for assuming that an automatic retry is safe.
Browser calls
The API does not provide CORS support for calls from arbitrary websites at other addresses. CORS consists of rules allowing a browser to make such calls between addresses. A valid key does not remove this limitation; public REST is not a universal interface for direct calls from other websites in a browser.
Return to Getting started to check access settings and the first read.