Response Envelope

All REST APIs return JSON. Clients should read both the HTTP status code and the code field in the response body.

Fields

Field	Type	Required	Description
code	string	Yes	Business code. Both success and error codes use uppercase underscore format
message	string	Yes	Human-readable description for display, logs, and troubleshooting only
requestId	string	Yes	Request ID to provide during troubleshooting
data	object	Depends on the response	Success data or structured information required to handle an error

Client Rules

• Clients must branch on HTTP status and code
• Clients must not branch on message
• message may change as wording is refined, but code must remain stable
• Clients must treat error data as code-specific structured details

Success Response

{
  "code": "SUCCESS",
  "message": "OK.",
  "requestId": "req_001",
  "data": {}
}

Error Response

Most error responses omit data:

{
  "code": "AUTH_INVALID",
  "message": "Invalid access token.",
  "requestId": "req_001"
}

An error may include data when clients need structured details to fix the request. For example:

{
  "code": "AUTH_SCOPE_DENIED",
  "message": "This operation requires the device:control permission. Update the API Client permissions in the Developer Console and obtain a new access token.",
  "requestId": "req_001",
  "data": {
    "requiredScope": "device:control"
  }
}

Design Notes

• Success and error responses keep a unified outer shape
• Most error responses omit data; code-specific errors may include structured remediation details
• COMMAND_ACCEPTED is a success-class business code and must include data
• Error data is defined by the business code and must not be assumed across all errors