Error Handling
See Supported Devices for more information.
The HomeWizard Energy API v2 and its documentation are in beta and subject to change.
When you perform an invalid request or something went wrong, the API will respond with an error message. You have to check if the HTTP status code returns 200 OK before parsing the result or 204 No Content if you expect no content (actions and set requests).
If you use an endpoint that returns JSON, you also will receive an object with some error information.
Error Codes
Each error is represented as a set of 'scope' and 'error' fields. The 'scope' field indicates the part of the request that caused the error, and the 'error' field provides a description of the error. For example user:name-invalid if you provide an invalid name for the user during the authorization flow.
List of Errors
| Code | Description |
|---|---|
request:invalid-json | Server was unable to parse the JSON data. |
json:no-parameters-recognized | JSON was correct, but no required parameters were found. |
json:parameter-invalid-type:<parameter> | Invalid type for a parameter, e.g. a string where a number is expected. |
json:parameter-missing:<parameter> | Required parameter is missing. |
json:parameter-not-exclusive | Two or more parameters are mutually exclusive. |
request:api-version-not-supported | Requested API version not supported, see versioning. |
request:internal-server-error | Something went wrong on the server side. |
request:too-large | Request too large. |
request:unknown-subscription | WebSocket subscription topic not recognized, see WebSocket subscriptions. |
request:unknown-type | WebSocket type parameter not recognized, see WebSocket structure. |
telegram:no-telegram-received | No telegram received, see telegram. |
user:creation-not-enabled | User creation is not enabled, button press required. |
user:invalid-prefix | Invalid name prefix provided, see create user. |
user:name-empty | Upon creating a user, the name was empty. |
user:name-invalid | Upon creating a user, the name contained invalid tokens, see create user. |
user:name-too-long | Upon creating a user, the name was too long. |
user:no-storage | No storage available to store a new user, delete existing users. |
user:not-found | Tried to delete a user which does not exist. |
user:unauthorized | User token is invalid or not authorized, see authorization. |
The list of error codes may be extended in the future. We recommend that you prepare for new error codes by having a generic error handling mechanism in place.
Examples
Not Authenticated
curl https://<IP ADDRESS>/api --insecure \
-H "Authorization: Bearer <INVALID_TOKEN>" \
-H "X-Api-Version: 2" \
https/1.1 401 Unauthorized
Content-Type: application/json
{
"error": "user:unauthorized"
}
Invalid Value
curl https://<IP ADDRESS>/api/system --insecure \
-X PUT \
-H "Authorization: Bearer <TOKEN>" \
-H "X-Api-Version: 2" \
-d '{"status_led_brightness_pct": 123}'
https/1.1 400 Bad Request
Content-Type: application/json
{
"error":"json:parameter-invalid-type:status_led_brightness_pct"
}