Alexa.ThermostatControllor.ErrorResponse Interface

If Alexa sends an Alexa.ThermostatController directive to your skill and you can't handle it successfully, respond with an Alexa.ThermostatControllor.ErrorResponse event. For more information, see ThermostatController.

Error response event

In the payload for the Alexa.ThermostatControllor.ErrorResponse, specify the type of the error and include a message with information about the error. For the list of Alexa.ThermostatControllor error types, see Error type values.

ErrorResponse event payload details

Field Description Type Required
type The type of error. String Yes
message The error message for the error. String Yes

ErrorResponse event format

{
"event": {
    "header": {
      "namespace": "Alexa.ThermostatControllor",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId" :  "<the endpoint identifier of the endpoint >" ,
    },
    "payload": {
      "type": "<error type>",
      "message": "<error message>"
    }
  }
}

Error type values

The following table shows the valid Alexa.ThermostatControllor 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](../device-apis/alexa-property-schemas.html#temperature) object named `minimumTemperatureDelta` that indicates the minimum allowable difference between setpoints.
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.ThermostatControllor error types, you can also use Alexa error types such as TEMPERATURE_VALUE_OUT_OF_RANGE. For more information, see Alexa.ErrorResponse error type values.

Examples

Synchronous error response example

{
  "event": {
    "header": {
      "namespace": "Alexa.ThermostatControllor",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "type": "REQUESTED_SETPOINTS_TOO_CLOSE",
      "message": "The setpoints are too close.",
      "minimumTemperatureDelta": {
          "value": 2.0,
          "scale": "CELSIUS"
      }
    }
  }
}

Synchronous error response example when the temperature is out of range

The following example uses the TEMPERATURE_VALUE_OUT_OF_RANGE error type from the Alexa.ErrorResponse interface.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "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"
        }
      }
    }
  }
}

Synchronous error response example when the set points are too close together

{
  "event": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "appliance-001"
    },
    "payload": {
      "type": "REQUESTED_SETPOINTS_TOO_CLOSE",
      "message": "The specified setpoints are too close together",
      "minimumTemperatureDelta": {
        "value": 2.0,
        "scale": "CELSIUS"
      }
    }
  }
}

Asynchronous error response example

If you respond asynchronously, include a correlation token and a scope with an authorization token.

{
  "event": {
    "header": {
      "namespace": "Alexa.ThermostatControllor",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint":{
      "scope":{
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "type": "THERMOSTAT_IS_OFF",
      "message": "The thermostat is currently off."
    }
  }
}