Home > Alexa > Alexa Skills Kit

Alexa.ErrorResponse Event

intro

When an error occurs while processing a directive, you should return an ErrorResponse event. 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. This information is not shared with the customer.

Error types described are not specific to a capability interfaces and can be used to respond to any directive.

type values

Type Description
ENDPOINT_UNREACHABLE Indicates a directive targeting an endpoint that 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.
NO_SUCH_ENDPOINT Indicates a directive that is sent to an endpoint that does not exist or no longer exists.
INVALID_VALUE Indicates a directive that attempts to set an invalid value for that endpoint. For example, use to indicate a request with an invalid heating mode, channel value or program value. When you return this error type, you can optionally specify the valid range using the validRange object.
VALUE_OUT_OF_RANGE Indicates a directive that attempts to set a value that is outside the numerical range accepted for that 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
TEMPERATURE_VALUE_OUT_OF_RANGE Indicates a directive that attempts to set a value that outside the numeric temperature range accepted for that thermostat.
INVALID_DIRECTIVE Indicates a directive that is invalid or malformed. For example, in the unlikely event an endpoint receives a request it does not support, you would return this error type.
FIRMWARE_OUT_OF_DATE Indicates a directive could not be handled because the firmware for a bridge or an endpoint is out of date.
HARDWARE_MALFUNCTION Indicates a directive could not be handled because a bridge or an endpoint has experienced a hardware malfunction.
RATE_LIMIT_EXCEEDED Indicates the maximum rate at which an endpoint or bridge can process directives has been exceeded.
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.
EXPIRED_AUTHORIZATION_CREDENTIAL Indicates that the authorization credential provided by Alexa has expired. For example, the OAuth2 access token for that customer has expired.
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.

Example ErrorResponse Event

{
"event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
      "payloadVersion": "3"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE",
      "message": "Unable to reach endpoint 12345 because it appears to be offline"
    }
  }
}

validRange object

Use the validRange object in VALUE_OUT_OF_RANGE error type to specify the minimumValue and maximumValue for a setting.

Example with validRange specified

{
"event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
      "payloadVersion": "3"
    },
     "payload": {
      "type": "VALUE_OUT_OF_RANGE",
      "message": "The specified value is out of range for this setting.",
      "validRange": {
        "minimumValue": 1000,
        "maximumValue": 10000
      }
    }
  }
}
Interface Description
Alexa.Video.ErrorResponse Defines an error message specific to video subscription playback.