Alexa.ThermostatController.Configuration.ErrorResponse Interface 3

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

Copied to clipboard.

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

Copied to clipboard.

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

Copied to clipboard.

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

Copied to clipboard.

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

Last updated: Oct 19, 2022