Error handling¶

Errors might occur for various reasons. Robust applications shall handle them and not assume that each API call will succeed.

HTTP status codes¶

As usual in REST APIs errors are returned as HTTP status codes. The documentation for each API call lists all possible errors which might occur.

Error code	Name	Description
200	OK	Request succeded
201	Created	A new resource was created
202	Accepted	Request will be processed but isn't finished yet
304	Not Modified	Is returned if the request had the If-None-Match header and the ETag on the resource was the same.
400	Bad request	The request was not formated as expected or missing parameters
401	Unauthorized	Authorization failed
403	Forbidden	The caller has no rights to access the requested URI
404	Resource Not Found	The requested resource (light, group, ...) was not found
503	Service Unavailable	The device is not connected to the network or too busy to handle further requests

---

JSON error objects¶

Further details of the errors are available as JSON object in the response body.

{
    "error": {
        "type": <error code>,
        "address": <ressource/parameter>,
        "description": <description>
    }
}

Field	Type	Description
type	Number	One of the error codes listed below.
address	String	The url which refers to the resource/parameter which caused the error.
description	String	The error description contains details on what went wrong.

Errors¶

Error	Description	Details
1	unauthorized user	This will be returned if the request had no valid apikey or if the apikey has not the rights to access a resource.
2	body contains invalid JSON	This will be returned if the JSON in the body couldn't be parsed.
3	resource, <resource>, not available	This will be returned if the requestet resource like a light or a group does not exist.
4	method, <method>, not available for resource, <resource>	This will be returned if the requested method (GET, PUT, POST or DELETE) is not supported for the resource.
5	missing parameters in body	This will be returned if the request didn't contain all required parameters.
6	parameter, <parameter>, not available	This will be returned if a parameter sent in the request is not supported.
7	invalid value, <value>, for parameter, <parameter>	This will be returned if a parameter hasn't the expected format or is out of range.
8	parameter, <parameter>, is not modifiable	This will be returned in an attempt to change a read only parameter.
11	too many items in list	Returned when rules request contains too many actions or conditions.
12	body contains invalid DDF bundle(s) data	Returned in an attempt upload a DDF bundle with invalid data.