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 cannot 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).