Alexa.ThermostatController.ErrorResponse Events

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 information, see ThermostatController.

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.

ErrorResponse event payload details

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 does not share this with the customer. String Yes

ErrorResponse event format

Copied to clipboard.

{
"event": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "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.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. See example here.
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 information, see Alexa.ErrorResponse error type values.

Examples

Synchronous response example

The following is an example error response that you send synchronously to Alexa. For the list of Alexa.ThermostatController error types, see Error type values.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "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"
      }
    }
  }
}

Asynchronous response example

The following is an example error response that you send asynchronously to the Alexa event gateway. If you respond asynchronously, include a correlation token and a scope with an authorization token. For more information, see Send Events to the Event Gateway.

For the list of Alexa.ThermostatController error types, see Error type values.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "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."
    }
  }
}

REQUESTED_SETPOINTS_TOO_CLOSE

The following is an example error response for the REQUESTED_SETPOINTS_TOO_CLOSE error type. For the list of Alexa.ThermostatController error types, see Error type values.

Copied to clipboard.

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

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.

For the list of Alexa.ThermostatController error types, see Error type values.

Copied to clipboard.

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