Error Codes

The following section lists the main error messages and their error codes, which can be content of the response to an API request. The errors are divided in to certain number ranges, which are explained in the coming subsections. If the request is successful, the response will have the 200 OK status code. Any other status code should be interpreted as an error and handled as such.

The following tables contain a mapping between responses error codes, the associated message and the HTTP status code. Some error codes might come with multiple HTTP status code based on the context of the error.

Table of contents:

General Error (1000 - 1999)

Code Message Description HTTP Status Codes
1000 An unknown error has occurred. An unknown error has occurred. 500
1001 Service unavailable. One of the backend services is unavailable or an unhandled error occurred in the service. -
1002 Service timeout. One of the backend services timed out. 408
1003 Internal API error. Internal API error. 500
1004 SHC invalid operation. SHC side exception or error. 400, 404, 500
1005 Missing argument or wrong value. One of the request parameters value is invalid or has the wrong value. 400
1006 Service too busy. The service is too busy and can't handle requests right now. 503
1007 Unsupported request. The request is not valid. 400
1008 Precondition failed. A precondition for the given operation was not met. The client may retry the operation after 3-5 minutes. 412

Authentication and Authorization (2000 – 2999)

Code Message Description HTTP Status Codes
2000 An unknown error has occurred during Authentication or Authorization process. Unknown error occurred during Authentication or Authorization. 400
2001 Access not allowed. No Ownership for SHC with given serial number. 403
2002 Invalid token request. The token request is invalid - malformed or wrong parameter values. 403
2003 Invalid client credentials. The client ID or password are invalid. 401
2004 The token signature is invalid. The token signature is invalid - it was not issued by the proper authority. -
2005 Failed to initialize user session. User session initialization failed. -
2006 A connection already exists for the current session. Another connection with the same token was initialized for the SHC. 409
2007 The lifetime of the token has expired. The lifetime of the token has expired. A refresh token request should be sent.. 401
2008 Login attempted from a different client provider. The combination client - username doesn’t match; the username tried to login using a client from another tenant (provider). 403
2009 Invalid user credentials. The username or password provided for token generation are invalid. 401
2010 Controller access not allowed. Access is is not allowed in the system. 403
2011 Insufficient permissions. Client or user does not have the appropriate permissions to execute the requested operation. 403
2012 Session not found. Session not initialized or disconnected. 424
2013 Account temporary locked. This account is currently locked. Please try again in X minutes. 403

Entities (3000 – 3499)

Code Message Description HTTP Status Codes
3000 The requested entity does not exist. The requested entity does not exist. 404
3001 The provided request content is invalid and can't be parsed. The provided content is mall formatted and can’t be parsed (JSON). 400
3002 No change performed. The performed change for entities contains no value. 304
3003 The provided entity already exists. The provided entity already exists. 409
3004 The provided interaction is not valid. The provided interaction is not valid. 400
3004 The provided interaction is not valid. The provided interaction is not valid. 400
3005 Too many entities of this type. The maximum number of entities of this type was already reached. 409

Products (3500 – 3999)

Code Message Description HTTP Status Codes
3500 Premium Services can't be directly enabled. Premium Services can be enabled only through the Webshop. 403
3501 Cannot remove a product that was paid. Paid products (by webshop/smart codes) cannot be removed. 403

Actions (4000 – 4999)

Code Message Description HTTP Status Codes
4000 The triggered action is invalid. The triggered action is invalid. 404
4001 Invalid parameter. One of the action parameters is invalid. 400
4002 Permission to trigger action not allowed. The user does not have the appropriate permissions to the trigger the action. 403
4003 Unsupported action type. The triggered action type is unsupported. 404

Configuration (5000 – 5999)

Code Message Description HTTP Status Codes
5000 The configuration could not be updated. There was an error updating the configuration. 400
5001 Could not obtain exclusive access on the configuration. The configuration is locked by another process. 409
5002 Communication with the SHC failed. Communication with the SHC failed. 404
5003 The owner did not accepted the TaC latest version. Latest version of terms and conditions and data privacy policy was not accepted by the user. 412
5004 One SHC already registered. Only one SHC can be registered per user. 409
5005 The user has no SHC. The user has no registered SHC device. 401
5006 Controller offline. The SHC is offline. 404
5009 Registration failure. The registration process failed. 404

In case the connection to the SmartHome Controller is interrupted (no internet access, no power, etc.) it takes about 60 seconds for the backend to detect this. This means that some of the first requests will result in a 5002 error code response. After the backend detects that the SHC is offline, all requests will result in a 5006 error code response.

SmartCodes (6000 – 6999)

Code Message Description HTTP Status Codes
6000 SmartCode request not allowed. Request not allowed or too many tries. Try again in 60 minutes. 403
6001 The SmartCode cannot be redeemed. Request not allowed. The requested smart code cannot be redeemed because it was already redeemed. 409
6002 Restricted access. Access restricted because too many invalid smart code pins were provided. 403

Updated on 01 Feb 2020