Alexa.Safety.ErrorResponse Interface 3

If Alexa sends a directive to your skill and you can't handle it successfully because of a safety concern, respond with an Alexa.Safety.ErrorResponse event.

ErrorResponse event

In the payload for the Alexa.Safety.ErrorResponse, specify the type of the error and include a message with information about the error. For the list of Alexa.Safety error types, see Error type values. You can send the error response in a synchronous or asynchronous response. For more details, see Alexa.ErrorResponse.

ErrorResponse event payload properties

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

Copied to clipboard.

{
"event": {
    "header": {
      "namespace": "Alexa.Safety",
      "name": "ErrorResponse",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpoint":{
        "endpointId": "Endpoint ID"
      },
    },
    "payload": {
      "type": "Error type",
      "message": "Error message"
    }
  }
}

Error type values

The following table shows the valid Alexa.Safety error types.

Error Type Description
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.
SAFETY_BEAM_BREACHED The endpoint can't handle the directive because a safety beam was breached, such as when an elevator door is closing and a person crosses the safety beam of the door. See example here.

In addition to the Alexa.Safety error types, you can also use Alexa error types. For more details, see Alexa.ErrorResponse error type values.

Alexa.Safety.ErrorResponse examples

The following examples show the payload for different error types.

OBSTACLE_DETECTED

The following is an example error response for the OBSTACLE_DETECTED error type.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Safety",
      "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": "OBSTACLE_DETECTED",
      "message": "There is an obstacle in the way."
    }
  }
}

SAFETY_BEAM_BREACHED

The following is an example error response for the SAFETY_BEAM_BREACHED error type. For the list of Alexa.Safety error types, see Error type values.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Safety",
      "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": "SAFETY_BEAM_BREACHED",
      "message": "The safety beam was breached."
    }
  }
}
Was this page helpful?

Last updated: Nov 22, 2023