Alexa.Safety.ErrorResponse Events

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.

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

Copied to clipboard.

{
"event": {
    "header": {
      "namespace": "Alexa.Safety",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId" :  "<the endpoint identifier of the endpoint >" ,
    },
    "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 information, see Alexa.ErrorResponse error type values.

Examples

Synchronous response example

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

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Safety",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "type": "OBSTACLE_DETECTED",
      "message": "There is an obstacle in the way."
    }
  }
}

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 more information, see Send Events to the Event Gateway.

For the list of Alexa.Safety error types, see Error type values.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Safety",
      "name": "ErrorResponse",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint":{
      "scope":{
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "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": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "type": "SAFETY_BEAM_BREACHED",
      "message": "The safety beam was breached."
    }
  }
}