Alexa.ErrorResponse Interface 3
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:
Alexa.AuthorizationController.ErrorResponse
Alexa.Commissionable.ReportCommissioningInformation.ErrorResponse
Alexa.Cooking.ErrorResponse
Alexa.DataController.ErrorResponse
Alexa.Safety.ErrorResponse
Alexa.SecurityPanelController.ErrorResponse
Alexa.ThermostatController.Configuration.ErrorResponse
Alexa.ThermostatController.ErrorResponse
Alexa.ThermostatController.Schedule.ErrorResponse
Alexa.Video.ErrorResponse
If you can handle a directive successfully, respond with an Alexa.Response
event instead
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 format
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint":{
"endpointId": "Endpoint ID"
},
"payload": {
"type": "Error type",
"message": "Error message"
}
}
}
Synchronous ErrorResponse
If you respond to the directive from your Lambda function, send a synchronous response. Include the correlationToken
set to the value from the directive request.
The following example shows a synchronous error response that you send to Alexa. For the list of error types, see error type values.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "3"
},
"endpoint":{
"endpointId": "Endpoint ID"
},
"payload": {
"type": "ENDPOINT_UNREACHABLE",
"message": "Unable to reach endpoint 12345 because it appears to be offline"
}
}
}
Asynchronous ErrorResponse
If you respond to the directive from your device cloud, send an asynchronous response to the Alexa event gateway. Include the correlation token and a scope with an authorization token. For details, see Send Events to the Event Gateway. When you send an asynchronous Alexa.ErrorResponse
to the gateway, Alexa sends an HTTP status code to indicate success or failure.
The following example shows an asynchronous error response that you send to the Alexa event gateway. For the list of error types, see error type values.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"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."
}
}
}
HTTP status codes
The following table shows the HTTP status code values that your skill might receive from the Alexa event gateway. If you receive an error, the payload
object contains a code
and description
field. Use these fields for logging only.
Status | Payload code | Description |
---|---|---|
|
— |
Request is authorized and the message is a syntactically valid event. The gateway accepted the event for further logical validation and processing. |
|
|
Message is invalid due to missing fields, incorrect values, or malformed JSON. Check your messages against the documentation to verify that your message contains all the required fields. |
|
|
Message didn't include the authorization token or the token is invalid, expired, or malformed. Refresh your token and retry the request. If a user disables your skill, that also invalidates the access token. Here, the user revoked authorization, and you can stop sending change reports for them. |
|
|
You're not allowed access to the event gateway. Make sure that you're sending the events to the correct regional endpoint. For example, send events in North America to the North American endpoint. |
|
|
Token doesn't have the required permissions. Make sure that the skill has permission to send Alexa events. For details, see Request Access to the Alexa Event Gateway. |
|
|
Account record associated with this directed identifier doesn't exist or has expired. This error can occur if the event was sent too late or with an invalid directed identifier. Verify that the directed identifier and authorization code are correct. |
|
|
Skill ID associated with this token wasn't found. This error occurs when user's access token was generated when the skill was in different stage, such as certification. Try disabling and re-enabling the skill for this user. |
|
|
Size of the event payload is too large. The maximum number of endpoints allowed in a request is 300. Send your message with smaller payloads. |
|
|
Number of requests is too high. Resend the message up to three times, with at least a one-second interval between each send attempt. |
|
|
Error occurred with Alexa, and the message wasn't processed. Resend the message up to three times, with at least a one-second interval between each send attempt. If problems persist, contact Amazon Support. |
|
|
Alexa couldn't accept the message. Resend the message up to three times, with at least a one-second interval between each attempt. If the problem persists, contact Amazon Support. |
Example 401 Unauthorized response body
The following example shows an error response.
HTTP/1.1 400 Bad Request
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close
{
"header": {
"namespace": "System",
"name": "Exception",
"messageId": "90c3fc62-4b2d-460c-9c8b-77251f1698a0"
},
"payload": {
"code": "INVALID_ACCESS_TOKEN_EXCEPTION",
"description": "The access token is invalid, expired, or malformed."
}
}
ErrorResponse event payload properties
Send an Alexa.ErrorResponse
in an Event
object.
Include the following information in the event.payload
parameter.
Property | Description | Type | Required |
---|---|---|---|
|
Type of error. Alexa shares this with the customer. |
String |
Yes |
|
Descriptive message for the error. Alexa doesn't share this with the customer. |
String |
Yes |
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 might 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_CONTROL_UNAVAILABLE | The endpoint control isn't available at this time, for example, due to no connectivity to a vehicle. Use this error type for connected vehicles with connectivity issues. When you send this error response, include a reason in the payload that indicates the why control is unavailable. For an example, see ENDPOINT_CONTROL_UNAVAILABLE. |
ENDPOINT_LOW_POWER | The endpoint can't handle the directive because the battery power is too low. For an example, see ENDPOINT_LOW_POWER. |
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 might be times when you should return a StateReport instead of this error. For more details, see Alexa.EndpointHealth . |
EXPIRED_AUTHORIZATION_CREDENTIAL | The authorization credential provided by Alexa has expired. For example, the OAuth 2.0 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 OAuth 2.0 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_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. |
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 . For an example, see NOT_SUPPORTED_IN_CURRENT_MODE. |
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. For an example, see NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE. |
PARTNER_APPLICATION_REDIRECTION | The endpoint can't handle the request. On receipt of this error, Alexa prompts the customer to check the partner app. |
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 specified termperature value is 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. For an example, see TEMPERATURE_VALUE_OUT_OF_RANGE. |
TOO_MANY_FAILED_ATTEMPTS | The number of allowed failed attempts, such as when entering a password, was exceeded. |
VALUE_OUT_OF_RANGE | The specified value is 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. For an example, see VALUE_OUT_OF_RANGE. |
ErrorResponse examples
The following examples show the payload for different error types.
ENDPOINT_CONTROL_UNAVAILABLE
The following is an example error response for the ENDPOINT_CONTROL_UNAVAILABLE
error type. Include a reason string in the payload to specify why control isn't available. For the list of error types, see error type values.
ENDPOINT_LOW_POWER
The following is an example error response for the ENDPOINT_LOW_POWER
error type.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"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.
{
"event": {
"header": {
"namespace": "Alexa.ColorTemperatureController",
"name": "ErrorResponse",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"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.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"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.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"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.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"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.
The following example shows the CurrentChargeLevelInPercentage
property.
{
"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 |
---|---|
|
The vehicle battery level is more than the requested level. |
|
The vehicle battery is charging. |
|
The vehicle battery level is 100%. |
|
The vehicle battery isn't connected to a charger. |
Reason values
When you send a ENDPOINT_CONTROL_UNAVAILABLE
error response, include a reason
string in the payload to indicate why endpoint control isn't available.
Property | Description |
---|---|
|
Deep sleep mode is a user-defined setting in an endpoint, such as a connected vehicle. The customer might solve this issue by turning off this mode. |
|
The endpoint is outside the range of the network connectivity service. |
|
The endpoint requires the customer to purchase or enable an internet plan. |
|
The device cloud can't connect to the endpoint for an unknown reason. |
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.
The following example shows the ValidRange
object.
{
"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.
The following example shows the ValidRange
object. with temperature.
{
"validRange": {
"minimumValue": {
"value": 15.0,
"scale": "CELSIUS"
},
"maximumValue": {
"value": 30.0,
"scale": "CELSIUS"
}
}
}
Related topics
- Alexa.AuthorizationController.ErrorResponse
- Alexa.Cooking.ErrorResponse
- Alexa.DataController.ErrorResponse
- Alexa.Safety.ErrorResponse
- Alexa.SecurityPanelController.ErrorResponse
- Alexa.SmartVision.ObjectDetectionSensor.ErrorResponse
- Alexa.ThermostatController.ErrorResponse
- Alexa.ThermostatController.Configuration.ErrorResponse
- Alexa.ThermostatController.Schedule.ErrorResponse
- Alexa.Video.ErrorResponse
Last updated: Feb 24, 2023