Response codes

In addition to standard HTTP status codes, the API returns control device response codes to give more precise, business-specific details about successes or errors encountered during requests. Those codes enable more granular handling of control device logic, useful for IoT devices and developers implementing success-aware and error-aware systems.

Response code summary

Code	Message	Meaning	Category
2000	Ok	Successful requests	Success
4000	Bad Request	Invalid input, malformed request	Client Error
4001	Unauthorized	No valid authentication provided	Client Error
4002	Payment Required	License or payment required	Client Error
4003	Forbidden	Access forbidden due to device policy	Client Error
4004	Not Found	Resource not found	Client Error
4013	Request Entity Too Large	Payload exceeds allowed size	Client Error
4022	Unprocessable Entity	Semantic errors	Client Error
4029	Too Many Requests	Rate limit exceeded	Client Error

Notes:

Control device response codes are numeric, but distinct from HTTP status codes.
They complement, not replace, the HTTP status code in the response.
For example, a 403 Forbidden HTTP status might include response code 4002 or 4013 to clarify the reason for the denial.

How to handle responses

Each API response includes both:

A HTTP status, and
A control code (code) in the JSON response body.

For example:


          {
            "code": 4002,
            "error": "You can not view the control device for the following reasons: the subscription is not active."
          }

Locally, the control device may use the HTTP status to classify the success or error, and the code to apply specific handling logic (e.g. user-facing messages, conditional retries, or escalation).

Best practices for device developers

Always check both the HTTP status and the code.
Fallback to the HTTP status code if code is not present.
Use code to implement fine-grained error handling (e.g. retry logic, billing prompts, UI messages).

Developer Notes

The control device response codes are stable and versioned.
Future API versions may introduce new codes, but existing meanings will not change.
You may match code values programmatically to determine the appropriate failure response (e.g. silent retry, show message, block action).