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',
  WEB_SOCKET_RECONNECTIONS_UNSET = 'WEB_SOCKET_RECONNECTIONS_UNSET',

  USER_LOCKED_OUT = 'USER_LOCKED_OUT',

  MEDIA_DEVICES_EMPTY_LABELS = 'MEDIA_DEVICES_EMPTY_LABELS',
  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',

  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

WEB_SOCKET_RECONNECTIONS_UNSET

Logic error, report to Keyless

USER_LOCKED_OUT

The user is locked out on the client-side

MEDIA_DEVICES_EMPTY_LABELS

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

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

Last updated 2 hours ago

Was this helpful?