ErrorResponse Events

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.

Use the Alexa.ErrorResponse event for the generic errors listed in error type values. If appropriate, use one of the following more specific error events instead: Cooking.ErrorResponse, Safety.ErrorResponse, SecurityPanelController.ErrorResponse, ThermostatController.ErrorResponse, Video.ErrorResponse.

ErrorResponse 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 doesn't share this message with the customer. String Yes

ErrorResponse event format

Copied to clipboard.

{
  "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. The different error types don't always result in different responses spoken by Alexa.

Field Description
ALREADY_IN_OPERATION The endpoint can't perform the requested operation 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 details, see Alexa.EndpointHealth.
CLOUD_CONTROL_DISABLED The user can't control the device over the internet, and should control the device manually instead.
ENDPOINT_BUSY The endpoint can't handle the directive because it's performing another action. The action might be a request to Alexa or a manual interaction.
ENDPOINT_LOW_POWER The endpoint can't handle the directive because the battery power is too low. See an example here.
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 doesn't have permissions to perform the specified action on the endpoint.
INTERNAL_ERROR An error occurred that isn't described by one of the other error types. For example, a runtime exception occurred. Amazon recommends that you always send a more specific error type, if possible.
INVALID_AUTHORIZATION_CREDENTIAL The authorization credential provided by Alexa is invalid. For example, the OAuth2 access token isn't valid for the customer's device cloud account.
INVALID_DIRECTIVE The directive isn't supported by the skill, or the directive is malformed.
INVALID_VALUE The directive contains a value that's not valid for the target endpoint. For example, an invalid heating mode, channel, or program value.
NO_SUCH_ENDPOINT The endpoint doesn't exist, or no longer exists.
NOT_CALIBRATED The endpoint can't handle the directive because it's in a calibration phase, such as warming up, or a user configuration isn't set up yet on the device.
NOT_SUPPORTED_IN_CURRENT_MODE The endpoint can't set the device 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 to indicate why the device can't be set to the new value. Valid values are COLOR, ASLEEP, NOT_PROVISIONED, OTHER. See an example here.
NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE The endpoint can't fulfill the request due to the current battery state. When you send this error response, include the currentChargeState property in the payload to indicate the battery state. You can optionally include the CurrentChargeLevelInPercentage property to indicate the battery level in percentage. See an example here.
NOT_IN_OPERATION The endpoint isn't 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 requests exceed the maximum rate at which an endpoint or bridge can process directives.
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 object in the payload that indicates the acceptable temperature range. See an example here.
TOO_MANY_FAILED_ATTEMPTS The number of allowed failed attempts, such as when entering a password, has been exceeded.
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 object in the payload that indicates the acceptable range. See an example here.

Examples

Synchronous response example

The following is an example error response that you send synchronously to Alexa. For the list of error types, see error type values.

Copied to clipboard.

{
  "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 response example

The following is an example error response that you send asynchronously to the Alexa event gateway. If you respond asynchronously, include a correlation token and a scope with an authorization token. For details, see Send Events to the Event Gateway.

Copied to clipboard.

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

ENDPOINT_LOW_POWER

The following is an example error response for the ENDPOINT_LOW_POWER error type. For the list of error types, see error type values.

Copied to clipboard.

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

NOT_SUPPORTED_IN_CURRENT_MODE

The following is an example error response for the NOT_SUPPORTED_IN_CURRENT_MODE error type. For the list of error types, see error type values.

Copied to clipboard.

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

NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE

The following is an example error response for the NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE error type. For the list of error types, see error type values.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "type": "NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE ",
      "message":"The vehicle has been charging",
      "currentChargeState": "ALREADY_CHARGED_TO_REQUIRED_LEVEL",
      "currentChargeLevelInPercentage": 75
    }
  }
}

TEMPERATURE_VALUE_OUT_OF_RANGE

The following is an example error response for the TEMPERATURE_VALUE_OUT_OF_RANGE error type. Include a validRange object in the payload to specify the minimum and maximum acceptable temperatures. For the list of error types, see error type values.

Copied to clipboard.

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

VALUE_OUT_OF_RANGE

The following is an example error response for the VALUE_OUT_OF_RANGE error type. Include a validRange object in the payload to specify the minimum and maximum acceptable values for a setting. For the list of error types, see error type values.

Copied to clipboard.

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

Properties and objects

Some error types include the following objects in the payload. For details, see error type values.

CurrentChargeLevelInPercentage property

When you send a NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE error response, include the currentChargeLevelInPercentage property in the payload. The currentChargeLevelInPercentage indicates the battery level in percentage. Valid values: 0 — 100. This property is optional.

CurrentChargeLevelInPercentage example

Copied to clipboard.

{
  "currentChargeLevelInPercentage": "100"
}

CurrentChargeState property

When you send a NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE error response, include the currentChargeState property in the payload. The currentChargeState indicates the current state of the battery.

The following table shows the valid values for the battery state.

Battery state Description

ALREADY_CHARGED_TO_REQUIRED_LEVEL

The vehicle battery level is more than the requested level.

CURRENTLY_CHARGING

The vehicle battery is charging.

FULLY_CHARGED

The vehicle battery level is 100%.

NOT_CONNECTED_TO_POWER

The vehicle battery isn't connected to a charger.

CurrentChargeState example

Copied to clipboard.

{
  "currentChargeState": "NOT_CONNECTED_TO_POWER"
}

ValidRange object

When you send a VALUE_OUT_OF_RANGE error response, include a validRange object in the payload to indicate the minimum and maximum acceptable values. This property is optional.

ValidRange example

Copied to clipboard.

{
  "validRange": {
    "minimumValue": 0,
    "maximumValue": 100
  }
}

ValidRange object with temperatures

When you send a TEMPERATURE_VALUE_OUT_OF_RANGE error response, include a validRange object in the payload to indicate the minimum and maximum acceptable temperatures. The minimum and maximum values contain temperature objects. This property is optional.

ValidRange with temperature example

Copied to clipboard.

{
  "validRange": {
    "minimumValue": {
      "value": 15.0,
      "scale": "CELSIUS"
    },
    "maximumValue": {
      "value": 30.0,
      "scale": "CELSIUS"
    }
  }
}