Error Handling

The KeylessAuth and KeylessEnroll classes emit 2 kind of error events:

• The all purpose "error" event

• The WebSocket specific "ws-error" event

Here's an example of how to handle these errors:

import { createKeylessAuth } from '@keyless/sdk-web'

function onKeylessError(error) {
  // will log the error code
  console.log(error.message)
}

const auth = createKeylessAuth()

// register the error event listener
addKeylessEventListener(auth, 'error', onKeylessError)

// opening a connection without the required options will always emit an error
openKeylessWebSocketConnection(auth, {})

Of course this example also applies to the KeylessEnroll class, each error contains the error code in the message, this is the enum which is also exported by the @keyless/sdk-web package:

enum KeylessError {
  OPTIONS_UNSET = 'OPTIONS_UNSET',
  VIDEO_ELEMENT_UNSET = 'VIDEO_ELEMENT_UNSET',
  VIDEO_ELEMENT_EVENT_LISTENERS_UNSET = 'VIDEO_ELEMENT_EVENT_LISTENERS_UNSET',
  WEB_SOCKET_MESSAGE_SET_UNSET = 'WEB_SOCKET_MESSAGE_SET_UNSET',

  USER_LOCKED_OUT = 'USER_LOCKED_OUT',

  MEDIA_DEVICES_EMPTY_VIDEO_INPUT_LABEL = 'MEDIA_DEVICES_EMPTY_VIDEO_INPUT_LABEL',
  MEDIA_DEVICES_NO_VIDEO_INPUTS = 'MEDIA_DEVICES_NO_VIDEO_INPUTS',

  SERVER_CUSTOMER_NOT_FOUND = 'SERVER_CUSTOMER_NOT_FOUND',
  SERVER_FACE_DOES_NOT_MATCH = 'SERVER_FACE_DOES_NOT_MATCH',
  SERVER_FORBIDDEN = 'SERVER_FORBIDDEN',
  SERVER_IMAGE_ENCRYPT_FAILED = 'SERVER_IMAGE_ENCRYPT_FAILED',
  SERVER_INTERNAL_ERROR = 'SERVER_INTERNAL_ERROR',
  SERVER_NO_ATTEMPTS_LEFT = 'SERVER_NO_ATTEMPTS_LEFT',
  SERVER_RECOGNITION_FAILED = 'SERVER_RECOGNITION_FAILED',
  SERVER_TIMEOUT = 'SERVER_TIMEOUT',
  SERVER_UNAVAILABLE_SERVICE = 'SERVER_UNAVAILABLE_SERVICE',
  SERVER_UNPROCESSABLE_EVENT = 'SERVER_UNPROCESSABLE_EVENT',
  SERVER_USER_ALREADY_ENROLLED = 'SERVER_USER_ALREADY_ENROLLED',
  SERVER_USER_NOT_FOUND = 'SERVER_USER_NOT_FOUND',
  SERVER_USER_LOCKED_OUT = 'SERVER_USER_LOCKED_OUT',
  SERVER_VALIDATION_FAILED = 'SERVER_VALIDATION_FAILED',

  SESSION_MANAGER_NOT_NULL = 'SESSION_MANAGER_NOT_NULL',
  SESSION_MANAGER_NULL = 'SESSION_MANAGER_NULL',
  SESSION_MANAGER_VIDEO_STREAM_UNDEFINED = 'SESSION_MANAGER_VIDEO_STREAM_UNDEFINED',

  EXCEPTION = 'EXCEPTION',
  RUNTIME_VIOLATION = 'RUNTIME_VIOLATION',

  SESSION_ID_UNSET = 'SESSION_ID_UNSET',

  CUSTOMER_UNSET = 'CUSTOMER_UNSET',
  KEY_DECODE_FAILED = 'KEY_DECODE_FAILED',
  KEY_UNSET = 'KEY_UNSET',
  KEY_ID_UNSET = 'KEY_ID_UNSET',
  USERNAME_UNSET = 'USERNAME_UNSET',
  WEB_SOCKET_URL_PARSE_FAILED = 'WEB_SOCKET_URL_PARSE_FAILED',
  WEB_SOCKET_URL_UNSET = 'WEB_SOCKET_URL_UNSET',

  WEB_ASSEMBLY_ABORTED = 'WEB_ASSEMBLY_ABORTED',
  WEB_ASSEMBLY_FACTORY_FAILED = 'WEB_ASSEMBLY_FACTORY_FAILED',
  WEB_ASSEMBLY_IMPORT_FAILED = 'WEB_ASSEMBLY_IMPORT_FAILED',
  WEB_ASSEMBLY_NOT_READY = 'WEB_ASSEMBLY_NOT_READY',
  WEB_ASSEMBLY_MODULE_NOT_FOUND = 'WEB_ASSEMBLY_MODULE_NOT_FOUND',

  WEB_SOCKET_ERROR = 'WEB_SOCKET_ERROR',
  WEB_SOCKET_OPEN = 'WEB_SOCKET_OPEN',
  WEB_SOCKET_TIMEOUT = 'WEB_SOCKET_TIMEOUT',
  WEB_SOCKET_UNEXPECTED_CLOSE = 'WEB_SOCKET_UNEXPECTED_CLOSE'
}

Errors Explanation

Error	Meaning
OPTIONS_UNSET	Logic error, report to Keyless
VIDEO_ELEMENT_UNSET	Invalid state error, createKeylessVideoElement was called before createKeylessMediaStream
VIDEO_ELEMENT_EVENT_LISTENERS_UNSET	Logic error, report to Keyless
WEB_SOCKET_MESSAGE_SET_UNSET	Logic error, report to Keyless
USER_LOCKED_OUT	The user is locked out on the client-side
MEDIA_DEVICES_EMPTY_VIDEO_INPUT_LABEL	The user did not grant the camera permissions
MEDIA_DEVICES_NO_VIDEO_INPUTS	The user does not have a camera
SERVER_CUSTOMER_NOT_FOUND	The customer does not exist, report to Keyless
SERVER_FACE_DOES_NOT_MATCH	The face captured during the stream does not match with the one enrolled
SERVER_FORBIDDEN	The authorization token is invalid
SERVER_IMAGE_ENCRYPT_FAILED	Logic error, report to Keyless
SERVER_INTERNAL_ERROR	Logic error, report to Keyless
SERVER_NO_ATTEMPTS_LEFT	The user burned through all their circuits, authentication is impossible without a new enrollment
SERVER_RECOGNITION_FAILED	Biometric error, contact Keyless for more details
SERVER_TIMEOUT	The client took too long to reply to the server or an internal request timed out
SERVER_UNAVAILABLE_SERVICE	The server failed to establish a connection to another service
SERVER_UNPROCESSABLE_EVENT	Logic error, report to Keyless
SERVER_USER_ALREADY_ENROLLED	The user is attempting an enrollment with a username that is already enrolled
SERVER_USER_NOT_FOUND	The user is attempting an authentication witha user that is not enrolled
SERVER_USER_LOCKED_OUT	The user is locked out on the server-side
SERVER_VALIDATION_FAILED	Logic error, report to Keyless
SESSION_MANAGER_NOT_NULL	Integration error, the attempt must be completed or disposed with deleteKeylessAuth or deleteKeylessEnroll, otherwise calling createKeylessAuth or createKeylessEnroll will trigger this error
SESSION_MANAGER_NULL	Integration error, the createKeylessAuth or createKeylessEnroll functions must be called before using createKeylessVideoStream, createKeylessVideoElement and openKeylessWebSocketConnection. This error can also trigger if you don't have the proper security headers to run Web Assembly in your server, check out https://docs.keyless.io/web-sdk/web-sdk-guide/prerequisites#security-headers
SESSION_MANAGER_VIDEO_STREAM_UNDEFINED	Integration error, the createKeylessMediaStream function must be called before createKeylessVideoElement
EXCEPTION	Generic web assembly error, report to Keyless
RUNTIME_VIOLATION	Tampering detection, contact Keyless for more details
SESSION_ID_UNSET	Logic error, report to Keyless
CUSTOMER_UNSET	Integration error, the customer.name option is either undefined or empty
KEY_DECODE_FAILED	Integration error, the key.value option is non decodable
KEY_UNSET	Integration error, the key.value option is either undefined or empty
KEY_ID_UNSET	Integration error, the key.id option is either undefined or empty
USERNAME_UNSET	Integration error, the username option is either undefined or empty
WEB_SOCKET_URL_PARSE_FAILED	Integration error, the ws.url option is not a valid URL
WEB_SOCKET_URL_UNSET	Integration error, the ws.url option is either undefined or empty
WEB_ASSEMBLY_ABORTED	The web assembly runtime aborted on an unexpected condition, report to Keyless
WEB_ASSEMBLY_FACTORY_FAILED	The web assembly initialization failed, report to Keyless
WEB_ASSEMBLY_IMPORT_FAILED	The web assembly import failed, report to Keyless
WEB_ASSEMBLY_NOT_READY	Integration error, importKeylessWebAssemblyModule was not called before using other APIs
WEB_ASSEMBLY_MODULE_NOT_FOUND	Logic error, report to Keyles
WEB_SOCKET_ERROR	Connection error, report to Keyless
WEB_SOCKET_OPEN	Connection error, report to Keyless
WEB_SOCKET_TIMEOUT	The server took too long to reply to the client
WEB_SOCKET_UNEXPECTED_CLOSE	Connection or logic error, report to Keyless

Web Components Error Handling

Handling errors in the web components is very similar to how they are handled in the @keyless/sdk-web library, so check out that part first because those errors are inherited by the web components: Errors Explanation

Of course the web components naturally have more complexity, let’s go in order with some examples on how to handle all the errors emitted by the web components.

Here's an example of handling the "error" event:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Auth</title>
    <style>
      * {
        box-sizing: border-box;
      }

      body {
        align-items: center;
        display: flex;
        justify-content: center;
        margin: 0;
        min-height: 100vh;
        padding: 8px;
      }

      kl-auth {
        border: 1px solid lightgray;
      }
    </style>
  </head>
  <body>
    <kl-auth
      customer="CUSTOMER_NAME"
      enable-camera-instructions
      key="IMAGE_ENCRYPTION_PUBLIC_KEY"
      key-id="IMAGE_ENCRYPTION_KEY_ID"
      lang="en"
      size="375"
      theme="light"
      transaction-data='DATA_FROM_CUSTOMER_SERVER_TO_BE_SIGNED'
      username="USERNAME"
      ws-url="KEYLESS_AUTHENTICATION_SERVICE_URL"
    ></kl-auth>
    <script src="./node_modules/@keyless/sdk-web-components/index.js" type="module"></script>
    <script>
      const auth = document.querySelector('kl-auth')

      auth.addEventListener('error', (event) => {
        // will print the error code
        console.error(event.message)
      })
    </script>
  </body>
</html>

We extend the native ErrorEvent browser implementation here, so you can find the error code quite easily inside the event message.

The error code can be anything from the @keyless/sdk-web KeylessError enum, with on top the errors of the web components, here’s their enums:

enum KeylessComponentsError {
  QUEUE_UNSET = 'QUEUE_UNSET',
  SYMBOL_UNSET = 'SYMBOL_UNSET',

  NONCANCELABLE = 'NONCANCELABLE'
}

Web Components Errors Explanation

QUEUE_UNSET	Logic error, report to Keyless
SYMBOL_UNSET	Logic error, report to Keyless
NONCANCELABLE	Logic error, report to Keyless