Alexa.SecurityPanelController.ErrorResponse Interface 3

If Alexa sends an Alexa.SecurityPanelController directive to your smart home add-on and you can’t handle it successfully, respond with an Alexa.SecurityPanelController.ErrorResponse event. For more details, see Alexa.SecurityPanelController Interface.

ErrorResponse event

In the payload for the Alexa.SecurityPanelController.ErrorResponse, specify the type of the error and include a message with information about the error. For the list of Alexa.SecurityPanelController 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

{
"event": {
    "header": {
      "namespace": "Alexa.SecurityPanelController",
      "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"
    }
  }
}

Error type values

The following table shows the valid Alexa.SecurityPanelController error type values.

Value	Description
`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`. See an example here. For more details, see arming a security system.
`BYPASS_NEEDED`	The security panel has open zones that the user must bypass before you can arm the security system. If you want users to bypass errors by using voice commands, include a list of the endpoints that need bypassing in the `endpointsNeedingBypass` field in the payload of your error response. Specify the friendly name for each endpoint so that Alexa can say it to the user. Include the `endpointId` for sensors that implement the Alexa.ContactSensor and Alexa.MotionSensor interfaces. If you don’t include a list of endpoints in the payload of your error response, Alexa tells the user to bypass manually. See an example here. For more details, see bypass by voice option.
`NOT_READY`	The security panel is not ready for arming and disarming. Use this error type when a user tries to control the security panel while it’s in installation mode.
`UNAUTHORIZED`	The PIN code is not correct.
`UNCLEARED_ALARM`	The security panel has an active alarm and the user tries to arm it. See an example here.
`UNCLEARED_TROUBLE`	The security panel has a trouble condition.

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

Alexa.SecurityPanelController.ErrorResponse examples

The following examples show the payload for different error types.

UNAUTHORIZED

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

{
  "event": {
    "header": {
      "namespace": "Alexa.SecurityPanelController",
      "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": "UNAUTHORIZED",
      "message": "The PIN code is not correct."
    }
  }
}

AUTHORIZATION_REQUIRED

The following is an example error response for the AUTHORIZATION_REQUIRED error type. Use this error type when the user attempts to switch directly from ARMED_AWAY to ARMED_NIGHT or ARMED_STAY without disarming the system first. For more details, see arming a security system.

{
  "event": {
    "header": {
      "namespace": "Alexa.SecurityPanelController",
      "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": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "type": "AUTHORIZATION_REQUIRED",
      "message": "You must disarm the system before you can set the requested arm state."
    }
  }
}

BYPASS_NEEDED

The following is an example error response for the BYPASS_NEEDED error type. Use this error type when there are open zone errors and the user must bypass the errors to arm the system. In this example you provide a list of endpoints that need to be bypassed, which enables the user to bypass the errors by voice. For more details, see bypass by voice option.

{
  "event": {
    "header": {
      "namespace": "Alexa.SecurityPanelController",
      "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": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "type": "BYPASS_NEEDED",
      "message": "Unable to arm the security panel because there are open sensors.",
      "endpointsNeedingBypass": [
        {
          "friendlyName": "side window sensor",
          "endpointId": "Endpoint ID"
        },
        {
          "friendlyName": "front door sensor",
          "endpointId": "Endpoint ID"
        },
        {
          "friendlyName": "water sensor"
        }
      ]
    }
  }
}

UNCLEARED_ALARM

The following is an example error response for the UNCLEARED_ALARM error type. Use this error type when the user attempts to arm a security system that’s in an active alarm state.

{
  "event": {
    "header": {
      "namespace": "Alexa.SecurityPanelController",
      "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": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "type": "UNCLEARED_ALARM",
      "message": "Unable to arm or disarm the security panel because it is in alarm status."
    }
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Alexa.SecurityPanelController.ErrorResponse Interface 3

ErrorResponse event

ErrorResponse event payload properties

ErrorResponse event format

Error type values

Alexa.SecurityPanelController.ErrorResponse examples

UNAUTHORIZED

AUTHORIZATION_REQUIRED

BYPASS_NEEDED

UNCLEARED_ALARM

​ErrorResponse event

​ErrorResponse event payload properties

​ErrorResponse event format

​Error type values

​Alexa.SecurityPanelController.ErrorResponse examples

​UNAUTHORIZED

​AUTHORIZATION_REQUIRED

​BYPASS_NEEDED

​UNCLEARED_ALARM

​Related topics

ErrorResponse event

ErrorResponse event payload properties

ErrorResponse event format

Error type values

Alexa.SecurityPanelController.ErrorResponse examples

UNAUTHORIZED

AUTHORIZATION_REQUIRED

BYPASS_NEEDED

UNCLEARED_ALARM

Related topics