Alexa.ErrorResponse Interface 3

If Alexa sends a request to your smart home add-on and you can’t handle the request successfully, respond with an Alexa.ErrorResponse event. An unsuccessful response means that the endpoint wasn’t able to complete the requested action. Specify the type of error and why it occurred. You can send the response 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:

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 error response

If you respond to the directive from your Amazon Web Services (AWS) 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 error response

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 add-on might receive from the Alexa event gateway. If you receive an error, the response body contains the error code and description. Use these fields for logging only.

Status	Payload code	Description
`202 Accepted`	—	Request is authorized and the message is a syntactically valid event. The gateway accepted the event for further logical validation and processing.
`400 Bad Request`	`INVALID_REQUEST_EXCEPTION`	Message is not valid 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.
`401 Unauthorized`	`INVALID_ACCESS_TOKEN_EXCEPTION`	Message didn’t include the authorization token or the token is expired, malformed, or not valid. Refresh your token and retry the request. If a user disables your add-on, that also invalidates the access token.
`403 Forbidden`	`SKILL_DISABLED_EXCEPTION`	The customer disabled your add-on. Stop sending events for the customer and delete any stored tokens in your system.
`403 Forbidden`	`SKILL_NEVER_ENABLED_EXCEPTION`	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. Otherwise, the customer never enabled your add-on.
`403 Forbidden`	`INSUFFICIENT_PERMISSION_EXCEPTION`	Token doesn’t have the required permissions. Make sure that the add-on has permission to send Alexa events. For details, see Request Access to the Alexa Event Gateway.
`404 Not Found`	`ACCOUNT_NOT_FOUND_EXCEPTION`	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 directed identifier that’s not valid. Verify that the directed identifier and authorization code are correct.
`404 Not Found`	`SKILL_NOT_FOUND_EXCEPTION`	Skill ID associated with this token wasn’t found. This error occurs when user’s access token was generated when the add-on was in different stage, such as certification. Try disabling and re-enabling the add-on for this user.
`413 Payload Too Large`	`REQUEST_ENTITY_TOO_LARGE_EXCEPTION`	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.
`429 Too Many Requests`	`THROTTLING_EXCEPTION`	Number of requests is too high. Resend the message up to three times, with at least a one-second interval between each send attempt.
`500 Internal Server Error`	`INTERNAL_SERVICE_EXCEPTION`	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.
`503 Service Unavailable`	`SERVICE_UNAVAILABLE_EXCEPTION`	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 error response body

The following example shows an error response.

HTTP/1.1 401 Unauthorized
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "Unique version 4 UUID"
  },
  "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`	Type of error. Alexa shares this with the customer.	String	Yes
`message`	Descriptive message for the error for logging and debugging purposes only. Alexa doesn’t share this with the customer.	String	Yes

Error type values

The following table shows the valid error types and the corresponding error interface to return. For details about the parameters for each error type, see the referenced interface. For troubleshooting tips for specific error types, see Troubleshooting Guide for Smart Home Add-ons.

Value	Description	Interface
`ALREADY_IN_OPERATION`	The endpoint can’t perform the requested operation because the endpoint is already in operation.	`Alexa.ErrorResponse`
`AUTHORIZATION_REQUIRED`	The current state of the security system is `ARMED_AWAY`, and the user tries to re-arm the system as `ARMED_STAY` or `ARMED_NIGHT`.	`Alexa.SecurityPanelController.ErrorResponse`
`BRIDGE_UNREACHABLE`	The bridge is unreachable or offline. For example, the bridge is off, disconnected from the customer’s local area network, or connectivity between the bridge and the device cloud was 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`.	`Alexa.ErrorResponse`
`BYPASS_NEEDED`	The security panel has open zones that the user must bypass before you can arm the security system.	`Alexa.SecurityPanelController.ErrorResponse`
`CLOUD_CONTROL_DISABLED`	The user can’t control the device over the internet, and should control the device manually instead.	`Alexa.ErrorResponse`
`CHILD_LOCK`	The child lock on the appliance is enabled.	`Alexa.Cooking.ErrorResponse`
`CONFIGURATION_UPDATE_NOT_ALLOWED`	Configuration changes aren’t allowed by the thermostat device. To accept configuration changes, the customer must interact with the device directly.	`Alexa.ThermostatController.Configuration.ErrorResponse`
`COOK_DURATION_TOO_LONG`	The requested duration is too long for the appliance to run in a safe manner.	`Alexa.Cooking.ErrorResponse`
`COOLING_LOCKOUT_TEMPERATURE_VALUE_OUT_OF_RANGE`	The cooling lockout temperature is outside the accepted range.	`Alexa.ThermostatController.Configuration.ErrorResponse`
`COOLING_STAGES_EXCEEDS_LIMIT`	The number of cooling stages exceeds the limit.	`Alexa.ThermostatController.Configuration.ErrorResponse`
`DATA_DELETION_NOT_SUPPORTED`	The device doesn’t support data deletion.	`Alexa.DataController.ErrorResponse`
`DATA_RETRIEVAL_NOT_SUPPORTED`	The device doesn’t support data retrieval.	`Alexa.DataController.ErrorResponse`
`DEVICE_STUCK`	The device is physically obstructed and unable to perform the requested action.	`Alexa.ErrorResponse`
`DISABLED_BY_USER`	Endpoint can’t provide a snapshot because the customer disabled the snapshot feature in the camera app.	`Alexa.SmartVision.SnapshotProvider.ErrorResponse`
`DO_NOT_DISTURB_MODE`	The endpoint is in do-not-disturb mode and can’t respond to the requested directive.	`Alexa.ErrorResponse`
`DOOR_CLOSED_TOO_LONG`	The door wasn’t opened and closed recently and the appliance is likely empty. For example, an attempt to start cooking when no food is present.	`Alexa.Cooking.ErrorResponse`
`DOOR_OPEN`	The appliance door is open. For example, an attempt to start cooking when the appliance door is open.	`Alexa.Cooking.ErrorResponse`
`DUAL_SETPOINTS_UNSUPPORTED`	The thermostat doesn’t support dual setpoints in the current mode.	`Alexa.ThermostatController.ErrorResponse`
`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.	`Alexa.ErrorResponse`
`ENDPOINT_CONTROL_UNAVAILABLE`	The endpoint control isn’t available at this time, for example, due to no connectivity to a device. When you send this error response, include `reason` in the payload.	`Alexa.ErrorResponse`
`ENDPOINT_LOW_POWER`	The endpoint can’t handle the directive because the battery power is too low.	`Alexa.ErrorResponse`
`ENDPOINT_UNREACHABLE`	The endpoint is unreachable or offline. For example, the endpoint is turned off, disconnected from the customer’s local area network, or connectivity between the endpoint and bridge or the endpoint and the device cloud was 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`.	`Alexa.ErrorResponse`
`EXPIRED_AUTHORIZATION_CREDENTIAL`	The authorization credential provided by Alexa has expired. For example, the OAuth 2.0 access token for the customer has expired.	`Alexa.ErrorResponse`
`FAILED_TO_BOOTSTRAP_COMMISSIONING_PROCESS`	Endpoint is reachable but is unable to accept local connection. For Matter, it might mean that the endpoint failed to put the device into commissioning mode.	`Alexa.Commissionable.ReportCommissioningInformation`
`FIRMWARE_OUT_OF_DATE`	The endpoint can’t handle the directive because it’s firmware is out of date.	`Alexa.ErrorResponse`
`HARDWARE_MALFUNCTION`	The endpoint can’t handle the directive because it has experienced a hardware malfunction.	`Alexa.ErrorResponse`
`HEATING_LOCKOUT_TEMPERATURE_VALUE_OUT_OF_RANGE`	The heating lockout temperature is outside the accepted range.	`Alexa.ThermostatController.Configuration.ErrorResponse`
`HEATING_STAGES_EXCEEDS_LIMIT`	The number of heating stages exceeds the limit.	`Alexa.ThermostatController.Configuration.ErrorResponse`
`INSUFFICIENT_PERMISSIONS`	Alexa doesn’t have permissions to perform the specified action on the endpoint.	`Alexa.ErrorResponse`
`INSUFFICIENT_RESOURCE`	To complete the requested operation, the device requires a resource to be refilled or replaced. When you send this error response, include `resourceType` in the payload to describe the resource.	`Alexa.ErrorResponse`
`INSUFFICIENT_SPACE`	Thermostat has insufficient space. This error might occur when the user set too many schedules and exceeded the device limit.	`Alexa.ThermostatController.Schedule.ErrorResponse`
`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. For add-on errors, the more accurate the error type specified, the better Alexa can guide customers through appropriate steps and a relevant speech response.	`Alexa.ErrorResponse`
`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.	`Alexa.ErrorResponse`
`INVALID_AUXILIARY_HEATING_SYSTEM_TYPE`	The specified auxiliary heating system isn’t support by the device.	`Alexa.ThermostatController.Configuration.ErrorResponse`
`INVALID_DIRECTIVE`	The directive isn’t supported by the add-on, or the directive is malformed.	`Alexa.ErrorResponse`
`INVALID_SYSTEM_TYPE`	The heating, ventilation, and air conditioning (HVAC) system type isn’t support by the device.	`Alexa.ThermostatController.Configuration.ErrorResponse`
`INVALID_TARGET_STATE`	The target state isn’t support by the device.	`Alexa.ThermostatController.Configuration.ErrorResponse`
`INVALID_TEMPERATURE_SCALE`	The temperature scale isn’t support by the device.	`Alexa.ThermostatController.Configuration.ErrorResponse`
`INVALID_TERMINAL_CONNECTION`	One or more terminal connections are invalid.	`Alexa.ThermostatController.Configuration.ErrorResponse`
`INVALID_VALUE`	The directive contains a value that’s not valid for the target endpoint. For example, an invalid heating mode, channel, or requested object class.	`Alexa.ErrorResponse` `Alexa.SmartVision.ObjectDetectionSensor.ErrorResponse`
`MAINTENANCE_REQUIRED`	The device requires the maintenance before starting the operation. When you send this error response, optionally include `maintenanceAction` in the payload to describe the action to fix the device.	`Alexa.ErrorResponse`
`MAX_COMMISSIONING_LIMIT_REACHED`	Endpoint was already commissioned with the maximum number of local hubs.	`Alexa.Commissionable.ReportCommissioningInformation`
`MISSING_SETUP_INFORMATION`	Required information for setup is missing from the directive.	`Alexa.ThermostatController.Configuration.ErrorResponse`
`NO_SUCH_ENDPOINT`	The endpoint doesn’t exist, or no longer exists.	`Alexa.ErrorResponse`
`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.	`Alexa.ErrorResponse`
`NOT_IN_OPERATION`	The endpoint isn’t in operation. For example, a smart home add-on can return a `NOT_IN_OPERATION` error when it receives a `RESUME` directive but the endpoint is the `OFF` mode.	`Alexa.ErrorResponse`
`NOT_READY`	The security panel isn’t ready for arming and disarming. Use this error type when a user tries to control the security panel when the panel is in installation mode.	`Alexa.SecurityPanelController.ErrorResponse`
`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`currentDeviceMode` in the payload. For an example, see `NOT_SUPPORTED_IN_CURRENT_MODE`.	`Alexa.ErrorResponse`
`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 `currentChargeState` and, optionally, `currentChargeLevelInPercentage` in the payload. For an example, see NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE.	`Alexa.ErrorResponse`
`OBSTACLE_DETECTED`	The endpoint can’t handle the directive because an obstacle is detected, such as when a user tries to close a door and there is a person or object blocking the door.	`Alexa.Safety.ErrorResponse`
`PARTNER_APPLICATION_REDIRECTION`	The endpoint can’t handle the request. On receipt of this error, Alexa prompts the customer to view the partner app.	`Alexa.ErrorResponse`
`POWER_LEVEL_NOT_SUPPORTED`	The endpoint can’t handle the directive because it doesn’t support the requested power level.	`Alexa.ErrorResponse`
`PREHEAT_REQUIRED`	The appliance must be preheated.	`Alexa.Cooking.ErrorResponse`
`PROBE_REQUIRED`	The temperature probe must be inserted.	`Alexa.Cooking.ErrorResponse`
`RATE_LIMIT_EXCEEDED`	The requests exceed the maximum rate at which an endpoint or bridge can process directives.	`Alexa.ErrorResponse`
`REMOTE_START_NOT_SUPPORTED`	Cooking remotely isn’t supported by the device.	`Alexa.Cooking.ErrorResponse`
`REMOVE_PROBE`	The temperature probe must be removed.	`Alexa.Cooking.ErrorResponse`
`REMOTE_START_DISABLED`	Cooking remotely was disabled and must be re-enabled before cooking.	`Alexa.Cooking.ErrorResponse`
`REQUESTED_SETPOINTS_TOO_CLOSE`	The setpoints are too close together.	`Alexa.ThermostatController.ErrorResponse`
`SAFETY_BEAM_BREACHED`	The endpoint can’t handle the directive because something breached the safety beam, such as when an elevator door is closing and a person crosses the safety beam of the door.	`Alexa.Safety.ErrorResponse`
`SUBSCRIPTION_REQUIRED`	The requested object class wasn’t enabled because a subscription is required.	`Alexa.SmartVision.ObjectDetectionSensor.ErrorResponse` `Alexa.SmartVision.SnapshotProvider.ErrorResponse`
`TEMPERATURE_VALUE_OUT_OF_RANGE`	The specified temperature 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`.	`Alexa.ErrorResponse`
`THERMOSTAT_IS_OFF`	The thermostat is off and can’t be turned on.	`Alexa.ThermostatController.ErrorResponse`
`TOO_MANY_FAILED_ATTEMPTS`	The number of allowed failed attempts, such as when entering a password, was exceeded.	`Alexa.ErrorResponse`
`TRIPLE_SETPOINTS_UNSUPPORTED`	The thermostat doesn’t support triple setpoints in the current mode.	`Alexa.ThermostatController.ErrorResponse`
`UNABLE_TO_CHARGE`	Due to a technical issue, the endpoint can’t charge and therefore can’t perform the directive request.	`Alexa.ErrorResponse`
`UNAUTHORIZED`	The PIN code is incorrect.	`Alexa.SecurityPanelController.ErrorResponse`
`UNCLEARED_ALARM`	The security panel has an active alarm and the user tries to arm it.	`Alexa.SecurityPanelController.ErrorResponse`
`UNSUPPORTED_THERMOSTAT_MODE`	The thermostat doesn’t support the specified mode.	`Alexa.ThermostatController.ErrorResponse`
`UNCLEARED_TROUBLE`	The security panel has a trouble condition.	`Alexa.SecurityPanelController.ErrorResponse`
`UNWILLING_TO_SET_SCHEDULE`	The thermostat can’t set the specified schedule.	`Alexa.ThermostatController.ErrorResponse`
`UNWILLING_TO_SET_VALUE`	The thermostat can’t set the value because it can damage the device or appliance.	`Alexa.ThermostatController.ErrorResponse`
`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`.	`Alexa.ErrorResponse`

ErrorResponse examples

The following examples show the payload for error types that include extra properties.

ENDPOINT_CONTROL_UNAVAILABLE

The following example shows the error response for the ENDPOINT_CONTROL_UNAVAILABLE error type. You include a reason string in the payload to specify why control isn’t available. 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_CONTROL_UNAVAILABLE",
      "message": "Device has no connectivity package enabled.",
      "reason": "NO_CONNECTIVITY_PACKAGE_ENABLED"
    }
  }
}

ENDPOINT_LOW_POWER

The following example shows the 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 example shows the error response for the NOT_SUPPORTED_IN_CURRENT_MODE 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_IN_CURRENT_MODE",
      "message": "The device is in demand response mode.",
      "currentDeviceMode": "DEMAND_RESPONSE"
    }
  }
}

NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE

The following example shows the 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 device has been charging",
      "currentChargeState": "ALREADY_CHARGED_TO_REQUIRED_LEVEL",
      "currentChargeLevelInPercentage": 75
    }
  }
}

TEMPERATURE_VALUE_OUT_OF_RANGE

The following example shows the 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 example shows the 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

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. The property is an Integer with valid values: 0–100. This property is optional. The following example shows the CurrentChargeLevelInPercentage property.

{
  "currentChargeLevelInPercentage": "100"
}

CurrentChargeState values

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 property is a String.

CurrentChargeState value	Description
`ALREADY_CHARGED_TO_REQUIRED_LEVEL`	The battery level is more than the requested level.
`CURRENTLY_CHARGING`	The battery is charging.
`FULLY_CHARGED`	The battery level is 100%.
`NOT_CONNECTED_TO_POWER`	The battery isn’t connected to a charger.

CurrentDeviceMode

When you send a NOT_SUPPORTED_IN_CURRENT_MODE error response, include the CurrentDeviceMode property in the payload. The CurrentDeviceMode indicates why the device can’t be set to the new value. The property is a String.

CurrentDeviceMode value	Description
`ASLEEP`	The device is asleep.
`COLOR`	The device is currently set to a color.
`DEMAND_RESPONSE`	The device is actively participating in a demand response event.
`ECO`	The device is in eco mode to reduce energy consumption.
`NOT_PROVISIONED`	The device isn’t provisioned.
`VACATION`	The device is in vacation mode to reduce energy consumption.
`OTHER`	Not supported for another reason.

MaintenanceAction

When you send a MAINTENANCE_REQUIRED error response, include an optional maintenanceAction property in the payload to indicate required repair. The property is a String.

MaintenanceAction value	Description
`EMPTY_BIN`	For devices, such as robotic vacuum cleaners with a bin that must be emptied manually.

Reason

When you send an ENDPOINT_CONTROL_UNAVAILABLE error response, include a reason property in the payload to indicate why endpoint control isn’t available. The property is a String.

Reason value	Description
`DEEP_SLEEP_MODE`	Deep sleep mode is a user-defined setting in an endpoint. The customer might solve this issue by turning off this mode.
`OUT_OF_NETWORK_CONNECTIVITY`	The endpoint is outside the range of the network connectivity service.
`NO_CONNECTIVITY_PACKAGE_ENABLED`	The endpoint requires the customer to purchase or enable an internet plan.
`UNKNOWN`	The device cloud can’t connect to the endpoint for an unknown reason.

ResourceType

When you send an INSUFFICIENT_RESOURCE error response, include a resourceType property in the payload to indicate the resource to replace. The property is a String.

ResourceType value	Description
`WATER`	For devices, such as robotic vacuum cleaners that mop, the water tank is low or empty.

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

Alexa errors

Errors can occur on the Alexa side after you send a response. Alexa might timeout waiting for the response or encounter errors when processing the response payload. These errors prevent completion of the user’s request. Alexa errors include the following exceptions:

SKILL_RESPONSE_TIMEOUT_EXCEPTION – Exception thrown when an add-on times out on an Alexa request to the add-on.
INVALID_SKILL_RESPONSE_EXCEPTION – Exception thrown when Alexa receives a response from the add-on that isn’t valid.
INVALID_ACCESS_TOKEN_EXCEPTION – Exception thrown by the Alexa event gateway when an event from your add-on includes an access token that’s expired, malformed, or not valid, or the token was missing. Retry the request one time.
SKILL_DISABLED_EXCEPTION – Exception thrown by the Alexa event gateway when the customer disabled your add-on and revoked authorization. You must stop sending events for this customer and delete any stored tokens for the customer in your system.
SKILL_NEVER_ENABLED_EXCEPTION – Exception thrown by the Alexa event gateway when the customer never enabled the skill, or you sent the event to the wrong regional endpoint. Do not retry the request.

You can view Alexa errors on the Capability Directives page in the Analytics tab of the Alexa developer console. For more details, see Error metrics.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

ErrorResponse event

ErrorResponse event format

Synchronous error response

Asynchronous error response

HTTP status codes

Example error response body

ErrorResponse event payload properties

Error type values

ErrorResponse examples

ENDPOINT_CONTROL_UNAVAILABLE

ENDPOINT_LOW_POWER

NOT_SUPPORTED_IN_CURRENT_MODE

NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE

TEMPERATURE_VALUE_OUT_OF_RANGE

VALUE_OUT_OF_RANGE

Properties and objects

CurrentChargeLevelInPercentage

CurrentChargeState values

CurrentDeviceMode

MaintenanceAction

Reason

ResourceType

ValidRange object

ValidRange object with temperatures

Alexa errors

​ErrorResponse event

​ErrorResponse event format

​Synchronous error response

​Asynchronous error response

​HTTP status codes

Example error response body

​ErrorResponse event payload properties

​Error type values

​ErrorResponse examples

​ENDPOINT_CONTROL_UNAVAILABLE

​ENDPOINT_LOW_POWER

​NOT_SUPPORTED_IN_CURRENT_MODE

​NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE

​TEMPERATURE_VALUE_OUT_OF_RANGE

​VALUE_OUT_OF_RANGE

​Properties and objects

​CurrentChargeLevelInPercentage

​CurrentChargeState values

​CurrentDeviceMode

​MaintenanceAction

​Reason

​ResourceType

​ValidRange object

​ValidRange object with temperatures

​Alexa errors

​Related topics

ErrorResponse event

ErrorResponse event format

Synchronous error response

Asynchronous error response

HTTP status codes

ErrorResponse event payload properties

Error type values

ErrorResponse examples

ENDPOINT_CONTROL_UNAVAILABLE

ENDPOINT_LOW_POWER

NOT_SUPPORTED_IN_CURRENT_MODE

NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE

TEMPERATURE_VALUE_OUT_OF_RANGE

VALUE_OUT_OF_RANGE

Properties and objects

CurrentChargeLevelInPercentage

CurrentChargeState values

CurrentDeviceMode

MaintenanceAction

Reason

ResourceType

ValidRange object

ValidRange object with temperatures

Alexa errors

Related topics