Error handling

HTTP status codes

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

Status 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 Invalid apikey, the caller has no permissions 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.

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

Error response body

Further details are returned in the response body as JSON array which may contain one or more error objects.

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

Response fields

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

Errors

Type Response description Description
1 unauthorized user No valid apikey was specified
2 body contains invalid JSON The JSON in the body couldn’t be parsed
3 resource, resource, not available The requested resource — light, group, etc. doesn’t exist
4 method, method, not available for resource, resource The requested method — GET, PUT, POST or DELETE is not supported for the resource
5 missing parameters in body The request didn’t contain all required parameters
6 parameter, parameter, not available A parameter in a request is not supported
7 invalid value, value, for parameter, parameter A parameter hasn’t the expected format or is out of range
8 parameter, parameter, is not modifiable Attempt to change a read only parameter
101 link button not pressed Attempt to create an apikey while the gateway was locked