Your Alexa Consoles
Sign In
Sign In

Alexa.ErrorResponse Interface

If Alexa sends a request to your skill and you can't handle it successfully, respond with an Alexa.ErrorResponse event. Specify the type of error and why it occurred. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.

Error response event

In the payload for the Alexa.ErrorResponse, specify the type of the error and include a message with information about the error. For the list of error types, see error type values.

ErrorResponse event payload details

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 does not share this with the customer. String Yes

ErrorResponse event format

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "type": "<error type>",
      "message": "<error message>"
    }
  }
}

Error type values

The following table shows the valid error types.

Field Description
ALREADY_IN_OPERATION The operation can't be performed because the endpoint is already in operation.
BRIDGE_UNREACHABLE The bridge is 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. For more information, see Alexa.EndpointHealth.
ENDPOINT_BUSY The endpoint can't handle the directive because it is performing another action, which may or may not have originated from a request to Alexa.
ENDPOINT_LOW_POWER The endpoint can't handle the directive because the battery power is too low.
ENDPOINT_UNREACHABLE The endpoint is 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. For more information, see Alexa.EndpointHealth.
EXPIRED_AUTHORIZATION_CREDENTIAL The authorization credential provided by Alexa has expired. For example, the OAuth2 access token for the customer has expired.
FIRMWARE_OUT_OF_DATE The endpoint can't handle the directive because it's firmware is out of date.
HARDWARE_MALFUNCTION The endpoint can't handle the directive because it has experienced a hardware malfunction.
INSUFFICIENT_PERMISSIONS Alexa does not have permissions to perform the specified action on the endpoint.
INTERNAL_ERROR An error occurred that can't be described by one of the other error types. For example, a runtime exception occurred. We recommend that you always send a more specific error type.
INVALID_AUTHORIZATION_CREDENTIAL The authorization credential provided by Alexa is invalid. For example, the OAuth2 access token is not valid for the customer's device cloud account.
INVALID_DIRECTIVE The directive is not supported by the skill, or is malformed.
INVALID_VALUE The directive contains a value that is not valid for the target endpoint. For example, an invalid heating mode, channel, or program value.
NO_SUCH_ENDPOINT The endpoint does not exist, or no longer exists.
NOT_CALIBRATED The endpoint can't handle the directive because it is in a calibration phase, such as warming up.
NOT_SUPPORTED_IN_CURRENT_MODE The endpoint can't be set to the specified value because of its current mode of operation. When you send this error response, include a field in the payload named currentDeviceMode that indicates why the device cannot be set to the new value. Valid values are COLOR, ASLEEP, NOT_PROVISIONED, OTHER.
NOT_IN_OPERATION The endpoint is not in operation. For example, a smart home skill can return a NOT_IN_OPERATION error when it receives a RESUME directive but the endpoint is the OFF mode.
POWER_LEVEL_NOT_SUPPORTED The endpoint can't handle the directive because it doesn't support the requested power level.
RATE_LIMIT_EXCEEDED The maximum rate at which an endpoint or bridge can process directives has been exceeded.
TEMPERATURE_VALUE_OUT_OF_RANGE The endpoint can't be set to the specified value because it's outside the acceptable temperature range. When you send this error response, optionally include a validRange field in the payload that indicates the acceptable temperature range. For more information, see examples. For additional thermostat-specific errors, see Alexa.ThermostatController.
VALUE_OUT_OF_RANGE The endpoint can't be set to the specified value because it's outside the acceptable range. For example, you can use this error when a customer requests a percentage value over 100. For temperature values, use TEMPERATURE_VALUE_OUT_OF_RANGE instead. When you send this error response, optionally include a validRange field in the payload that indicates the acceptable range. For more information, see examples.

Examples

Synchronous error response example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE",
      "message": "Unable to reach endpoint 12345 because it appears to be offline"
    }
  }
}

Asynchronous error response example

If you respond asynchronously, include a correlation token and a scope with an authorization token.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint":{
      "scope":{
        "type":"BearerToken",
        "token":"access-token-from-Amazon"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE",
      "message": "Unable to reach endpoint 12345 because it appears to be offline"
    }
  }
}

NOT_SUPPORTED_IN_CURRENT_MODE error response example

{
  "event": {
    "header": {
      "namespace": "Alexa.ColorTemperatureController",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "type": "NOT_SUPPORTED_IN_CURRENT_MODE",
      "message": "The light is currently set to a color.",
      "currentDeviceMode": "COLOR"
    }
  }
}

VALUE_OUT_OF_RANGE error response example

Use the validRange object with the VALUE_OUT_OF_RANGE error type to specify the minimum and maximum acceptable values for a setting.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "type": "VALUE_OUT_OF_RANGE",
      "message": "The percent value cannot exceed 100.",
      "validRange": {
        "minimumValue": 0,
        "maximumValue": 100
      }
    }
  }
}

TEMPERATURE_VALUE_OUT_OF_RANGE error response example

Use the validRange object with the TEMPERATURE_VALUE_OUT_OF_RANGE error type to specify the minimum and maximum acceptable temperatures. The minimum and maximum values contain temperature objects.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "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"
        }
      }
    }
  }
}

ENDPOINT_LOW_POWER error response example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "type": "ENDPOINT_LOW_POWER",
      "message": "The lock battery is low",
      "percentageState": 5
    }
  }
}