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

TypeDescriptionPayload/Notes
BRIDGE_UNREACHABLEIndicates 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_BUSYIndicates 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_POWERIndicates the directive could not be completed because the target endpoint has low batteries.None
ENDPOINT_UNREACHABLEIndicates 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_CREDENTIALIndicates that the authorization credential provided by Alexa has expired. For example, the OAuth2 access token for that customer has expired.None
FIRMWARE_OUT_OF_DATEIndicates a directive could not be handled because the firmware for a bridge or an endpoint is out of date.None
HARDWARE_MALFUNCTIONIndicates a directive could not be handled because a bridge or an endpoint has experienced a hardware malfunction.None
INTERNAL_ERRORIndicates 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_CREDENTIALIndicates 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_DIRECTIVEIndicates a directive is not valid for this skill or is malformed.None
INVALID_VALUEIndicates 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_MODEIndicates 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_RANGEIndicates 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.ThermostatControllerOptionally 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_RANGEIndicates 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_RANGEOptionally specify the valid range using the validRange object, which contains minimumValue and maximumValue fields. See the the VALUE_OUT_RANGE example.

Example 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:

ErrorResponse