Alexa.ThermostatController.ErrorResponse Interface 3

If Alexa sends an Alexa.ThermostatController directive to your skill 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

Copied to clipboard.

{
"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.

Copied to clipboard.

{
  "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.

Copied to clipboard.

{
  "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.

Copied to clipboard.

{
  "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.

Copied to clipboard.

{
  "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"
        }
      }
    }
  }
}
Was this page helpful?

Last updated: Nov 22, 2023