Alexa.ErrorResponse
When an error occurs while processing a control or query directive, you should return an ErrorResponse event, which is in the Alexa namespace. This message must include a payload that specifies the type of error and why it occurred.
Error Message Format
The payload of an ErrorResponse event must specify a type and a message.
type: One of the accepted type values that indicates the kind of error that has occurred. Alexa uses this attribute to respond to the customer appropriately.message: String that provides more information about the error for logging purposes. This information is not shared with the customer.
Depending on the type there may be additional payload contents.
Error types described are not specific to a capability interfaces and can be used to respond to any control or query directive. If an error such as an expired token occurs during a discovery request, return an empty endpoint array and not an error. For errors specific to an interface, see the interface topic.
Error type values
| Type | Description | Payload/Notes |
|---|---|---|
| BRIDGE_UNREACHABLE | Indicates the target bridge endpoint is currently unreachable or offline. For example, the bridge might be turned off, disconnected from the customer's local area network, or connectivity between the bridge and the device cloud might have been lost. | When you respond to a ReportState directive, there may be times when you should return a StateReport instead of this error. See Alexa.EndpointHealth for more details. |
| ENDPOINT_BUSY | Indicates the target endpoint cannot respond because it is performing another action, which may or may not have originated from a request to Alexa. | None |
| ENDPOINT_LOW_POWER | Indicates the directive could not be completed because the target endpoint has low batteries. | None |
| ENDPOINT_UNREACHABLE | Indicates the target endpoint is currently unreachable or offline. For example, the endpoint might be turned off, disconnected from the customer's local area network, or connectivity between the endpoint and bridge or the endpoint and the device cloud might have been lost. | When you respond to a ReportState directive, there may be times when you should return a StateReport instead of this error. See Alexa.EndpointHealth for more details. |
| EXPIRED_AUTHORIZATION_CREDENTIAL | Indicates that the authorization credential provided by Alexa has expired. For example, the OAuth2 access token for that customer has expired. | None |
| FIRMWARE_OUT_OF_DATE | Indicates a directive could not be handled because the firmware for a bridge or an endpoint is out of date. | None |
| HARDWARE_MALFUNCTION | Indicates a directive could not be handled because a bridge or an endpoint has experienced a hardware malfunction. | None |
| INTERNAL_ERROR | Indicates an error that cannot be accurately described as one of the other error types occurred while you were handling the directive. For example, a generic runtime exception occurred while handling a directive. Ideally, you will never send this error event, but instead send a more specific error type. | None |
| INVALID_AUTHORIZATION_CREDENTIAL | Indicates that the authorization credential provided by Alexa is invalid. For example, the OAuth2 access token is not valid for the customer's device cloud account. | None |
| INVALID_DIRECTIVE | Indicates a directive is not valid for this skill or is malformed. | None |
| INVALID_VALUE | Indicates a directive contains an invalid value for the target endpoint. For example, use to indicate a request with an invalid heating mode, channel value or program value. | None |
| NO_SUCH_ENDPOINT | Indicates the target endpoint does not exist or no longer exists. | None |
| NOT_SUPPORTED_IN_CURRENT_MODE | Indicates the target endpoint cannot be set to the specified value because of its current mode of operation. | Requires a currentDeviceMode field that indicates why the device cannot be set to a new value. Valid values are COLOR, ASLEEP, NOT_PROVISIONED, OTHER. See Alexa.ColorTemperatureControl for an example. |
| RATE_LIMIT_EXCEEDED | Indicates the maximum rate at which an endpoint or bridge can process directives has been exceeded. | None |
| TEMPERATURE_VALUE_OUT_OF_RANGE | Indicates a directive that contains a value that outside the numeric temperature range accepted for the target thermostat. For more thermostat-specific errors, see the error section of the Alexa.ThermostatController interface. Note that the namespace for thermostat-specific errors is Alexa.ThermostatController | Optionally specify the valid range for the temperature using the validRange object. For this error type the minimum and maximum values are Temperature objects. See the TEMPERATURE_VALUE_OUT_OF_RANGE example |
| VALUE_OUT_OF_RANGE | Indicates a directive contains a value that is outside the numerical range accepted for the target endpoint. For example, use to respond to a request to set a percentage value over 100 percent. For temperature values, use TEMPERATURE_VALUE_OUT_OF_RANGE | Optionally specify the valid range using the validRange object, which contains minimumValue and maximumValue fields. See the the VALUE_OUT_RANGE example. |
Example Synchronous ErrorResponse {example-errorresponse}
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint":{
"endpointId":"appliance-001"
},
"payload": {
"type": "ENDPOINT_UNREACHABLE",
"message": "Unable to reach endpoint 12345 because it appears to be offline"
}
}
}
Example Asynchronous ErrorResponse
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint":{
"scope":{
"type":"BearerToken",
"token":"Alexa-access-token"
},
"endpointId":"appliance-001"
},
"payload": {
"type": "ENDPOINT_UNREACHABLE",
"message": "Unable to reach endpoint 12345 because it appears to be offline"
}
}
}
validRange object
A valid range contains one or more objects to indicate the valid values for a setting. Use the validRange object in VALUE_OUT_OF_RANGE error type to specify the minimumValue and maximumValue for a setting.
When used with a ThermostatController, validRange contains one or more Temperature objects.
Example VALUE_OUT_RANGE error
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint":{
"scope":{
"type":"BearerToken",
"token":"Alexa-access-token"
},
"endpointId":"appliance-001"
},
"payload": {
"type": "VALUE_OUT_OF_RANGE",
"message": "The color temperature cannot be set to 500.",
"validRange": {
"minimumValue": 1000,
"maximumValue": 10000
}
}
}
}
Example TEMPERATURE_VALUE_OUT_OF_RANGE error
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"BearerToken": "Alexa-access-token"
},
"endpointId" : "<the endpoint identifier of the endpoint >" ,
},
"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"
}
}
}
}
}
Additional Sample Code
See the sample request and response messages in the Alexa smart home GitHub repo: