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 codeNameDescription
200OKRequest succeded
201CreatedA new resource was created
202AcceptedRequest will be processed but isn't finished yet
304Not ModifiedIs returned if the request had the If-None-Match header and the ETag on the resource was the same.
400Bad requestThe request was not formated as expected or missing parameters
401UnauthorizedAuthorization failed
403ForbiddenThe caller has no rights to access the requested URI
404Resource Not FoundThe requested resource (light, group, ...) was not found
503Service UnavailableThe 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>
    }
}
FieldTypeDescription
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

ErrorDescriptionDetails
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.