Alexa.ThermostatController.Configuration.ErrorResponse Interface 3

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

ErrorResponse event

In the payload for the Alexa.ThermostatController.Configuration.ErrorResponse, specify the type of the error and include a message with information about the error. For the list of Alexa.ThermostatController.Configuration 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 parameters

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

ErrorResponse event example

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

Error type values

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

Error Type	Description
`CONFIGURATION_UPDATE_NOT_ALLOWED`	Configuration changes aren’t allowed by the thermostat device. To accept configuration changes, the customer must interact with the device directly.
`MISSING_SETUP_INFORMATION`	Required information for setup is missing from the directive.
`INVALID_TARGET_STATE`	The target state isn’t support by the device.
`INVALID_TEMPERATURE_SCALE`	The temperature scale isn’t support by the device.
`INVALID_TERMINAL_CONNECTION`	One or more terminal connections are invalid.
`INVALID_SYSTEM_TYPE`	The HVAC system type isn’t support by the device.
`HEATING_STAGES_EXCEEDS_LIMIT`	The number of heating stages exceeds the limit. Include a [validRange](../device-apis/alexa-errorresponse.html#valid-range) object in the payload to indicate the acceptable range.
`COOLING_STAGES_EXCEEDS_LIMIT`	The number of cooling stages exceeds the limit. Include a [validRange](../device-apis/alexa-errorresponse.html#valid-range) object in the payload to indicate the acceptable range.
`INVALID_AUXILIARY_HEATING_SYSTEM_TYPE`	The specified auxiliary heating system isn’t support by the device.
`COOLING_LOCKOUT_TEMPERATURE_VALUE_OUT_OF_RANGE`	The cooling lockout temperature is outside the accepted range. Include a [validRange](../device-apis/alexa-errorresponse.html#valid-range) object in the payload to indicate the acceptable range.
`HEATING_LOCKOUT_TEMPERATURE_VALUE_OUT_OF_RANGE`	The heating lockout temperature is outside the accepted range. Include a [validRange](../device-apis/alexa-errorresponse.html#valid-range) object in the payload to indicate the acceptable range.

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

Alexa.ThermostatController.Configuration.ErrorResponse examples

The following examples show the payload for different error types.

INVALID_TERMINAL_CONNECTION

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

{
    "event": {
        "header": {
            "namespace": "Alexa.ThermostatController.Configuration",
            "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": "INVALID_TERMINAL_CONNECTION",
            "message": "Terminal U2 not supported."
        }
    }
}

CONFIGURATION_UPDATE_NOT_ALLOWED

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

{
    "event": {
        "header": {
            "namespace": "Alexa.ThermostatController.Configuration",
            "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 bearer token"
            },
            "endpointId": "Endpoint id"
        },
        "payload": {
            "type": "CONFIGURATION_UPDATE_NOT_ALLOWED",
            "message": "The device is already updating configuration."
        }
    }
}

COOLING_LOCKOUT_TEMPERATURE_VALUE_OUT_OF_RANGE

The following is an example error response for the COOLING_LOCKOUT_TEMPERATURE_VALUE_OUT_OF_RANGE error type. 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.ThermostatController.Configuration",
            "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": "COOLING_LOCKOUT_TEMPERATURE_VALUE_OUT_OF_RANGE",
            "message": ".",
            "validRange": {
                "minimumValue": {
                    "value": 60.0,
                    "scale": "FAHRENHEIT"
                },
                "maximumValue": {
                    "value": 80.0,
                    "scale": "FAHRENHEIT"
                }
            }
        }
    }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Alexa.ThermostatController.Configuration.ErrorResponse Interface 3

ErrorResponse event

ErrorResponse event parameters

ErrorResponse event example

Error type values

Alexa.ThermostatController.Configuration.ErrorResponse examples

INVALID_TERMINAL_CONNECTION

CONFIGURATION_UPDATE_NOT_ALLOWED

COOLING_LOCKOUT_TEMPERATURE_VALUE_OUT_OF_RANGE

​ErrorResponse event

​ErrorResponse event parameters

​ErrorResponse event example

​Error type values

​Alexa.ThermostatController.Configuration.ErrorResponse examples

​INVALID_TERMINAL_CONNECTION

​CONFIGURATION_UPDATE_NOT_ALLOWED

​COOLING_LOCKOUT_TEMPERATURE_VALUE_OUT_OF_RANGE

​Related topics

ErrorResponse event

ErrorResponse event parameters

ErrorResponse event example

Error type values

Alexa.ThermostatController.Configuration.ErrorResponse examples

INVALID_TERMINAL_CONNECTION

CONFIGURATION_UPDATE_NOT_ALLOWED

COOLING_LOCKOUT_TEMPERATURE_VALUE_OUT_OF_RANGE

Related topics