Alexa.ThermostatController.ErrorResponse Interface 3

If Alexa sends an Alexa.ThermostatController directive to your smart home add-on and you can’t handle it successfully, respond with an Alexa.ThermostatController.ErrorResponse event. For more details, see Alexa.ThermostatController. For generic errors, use the Alexa.ErrorResponse event.

ErrorResponse event

In the payload for the Alexa.ThermostatController.ErrorResponse, specify the type of the error and include a message with information about the error. For the list of Alexa.ThermostatController error types, see Error type values. You can send the error response in a synchronous or asynchronous response. For more details, see Alexa.ErrorResponse.

ErrorResponse event format

{
"event": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ErrorResponse",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "type": "Error type",
      "message": "Error message"
    }
  }
}

ErrorResponse event payload properties

Field	Description	Type	Required
`type`	The type of error. Alexa shares this with the customer.	String	Yes
`message`	The error message for the error. Alexa doesn’t share this with the customer.	String	Yes

Error type values

The following table shows the valid Alexa.ThermostatController error types.

Error Type	Description
`REQUESTED_SETPOINTS_TOO_CLOSE`	The setpoints are too close together. When you send this error response, optionally include a `Temperature` object named `minimumTemperatureDelta` that indicates the minimum allowable difference between setpoints. For an example, see REQUESTED_SETPOINTS_TOO_CLOSE example.
`THERMOSTAT_IS_OFF`	The thermostat is off and can’t be turned on.
`UNSUPPORTED_THERMOSTAT_MODE`	The thermostat doesn’t support the specified mode.
`DUAL_SETPOINTS_UNSUPPORTED`	The thermostat doesn’t support dual setpoints in the current mode.
`TRIPLE_SETPOINTS_UNSUPPORTED`	The thermostat doesn’t support triple setpoints in the current mode.
`UNWILLING_TO_SET_SCHEDULE`	The thermostat can’t set the specified schedule.
`UNWILLING_TO_SET_VALUE`	The thermostat can’t set the value because it can damage the device or appliance.

In addition to the Alexa.ThermostatController error types, you can also use Alexa error types such as TEMPERATURE_VALUE_OUT_OF_RANGE. For more details, see Alexa.ErrorResponse error type values.

Alexa.ThermostatController.ErrorResponse examples

The following examples show the payload for different error types.

REQUESTED_SETPOINTS_TOO_CLOSE

The following is an example error response for the REQUESTED_SETPOINTS_TOO_CLOSE error type.

{
  "event": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ErrorResponse",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "type": "REQUESTED_SETPOINTS_TOO_CLOSE",
      "message": "The setpoints are too close.",
      "minimumTemperatureDelta": {
          "value": 2.0,
          "scale": "CELSIUS"
      }
    }
  }
}

THERMOSTAT_IS_OFF

The following is an example error response for the THERMOSTAT_IS_OFF error type.

{
  "event": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ErrorResponse",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint":{
      "scope":{
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "type": "THERMOSTAT_IS_OFF",
      "message": "The thermostat is currently off."
    }
  }
}

REQUESTED_SETPOINTS_TOO_CLOSE

The following is an example error response for the REQUESTED_SETPOINTS_TOO_CLOSE error type.

{
  "event": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ErrorResponse",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "type": "REQUESTED_SETPOINTS_TOO_CLOSE",
      "message": "The specified setpoints are too close together",
      "minimumTemperatureDelta": {
        "value": 2.0,
        "scale": "CELSIUS"
      }
    }
  }
}

TEMPERATURE_VALUE_OUT_OF_RANGE

The following is an example error response for the TEMPERATURE_VALUE_OUT_OF_RANGE error type from the Alexa.ErrorResponse interface. Include a validRange object in the payload to specify the minimum and maximum acceptable temperatures. The minimum and maximum values contain Temperature objects.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "type": "TEMPERATURE_VALUE_OUT_OF_RANGE",
      "message": "The requested temperature of -15 is out of range.",
      "validRange": {
        "minimumValue": {
          "value": 15.0,
          "scale": "CELSIUS"
        },
        "maximumValue": {
          "value": 30.0,
          "scale": "CELSIUS"
        }
      }
    }
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Alexa.ThermostatController.ErrorResponse Interface 3

ErrorResponse event

ErrorResponse event format

ErrorResponse event payload properties

Error type values

Alexa.ThermostatController.ErrorResponse examples

REQUESTED_SETPOINTS_TOO_CLOSE

THERMOSTAT_IS_OFF

REQUESTED_SETPOINTS_TOO_CLOSE

TEMPERATURE_VALUE_OUT_OF_RANGE

​ErrorResponse event

​ErrorResponse event format

​ErrorResponse event payload properties

​Error type values

​Alexa.ThermostatController.ErrorResponse examples

​REQUESTED_SETPOINTS_TOO_CLOSE

​THERMOSTAT_IS_OFF

​REQUESTED_SETPOINTS_TOO_CLOSE

​TEMPERATURE_VALUE_OUT_OF_RANGE

​Related topics

ErrorResponse event

ErrorResponse event format

ErrorResponse event payload properties

Error type values

Alexa.ThermostatController.ErrorResponse examples

REQUESTED_SETPOINTS_TOO_CLOSE

THERMOSTAT_IS_OFF

REQUESTED_SETPOINTS_TOO_CLOSE

TEMPERATURE_VALUE_OUT_OF_RANGE

Related topics