Error handling

The PingOne Recognize Web SDK can generate a variety of errors when processing authentication (KeylessAuth) and enrollment (KeylessEnroll) requests.

Error types

The PingOne Recognize Web SDK generates the following error types:

General error events common to web applications
WebSocket specific (ws-error) errors

Registering event listeners

To handle errors, register an error event listener, as shown in the following example:

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, {})

Enrollment components, such as KeylessEnroll, also support error event listeners.

Handling errors

When errors occur, the error object passed to the event listener contains an error code defined in the KeylessError enumeration exported by the @keyless/sdk-web package:

Details

enum KeylessError {
  FRAME_RESULTS_SET_UNSET = 'FRAME_RESULTS_SET_UNSET',
  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',

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

  MEDIA_STREAM_ABORT = 'MEDIA_STREAM_ABORT',
  MEDIA_STREAM_INVALID_STATE = 'MEDIA_STREAM_INVALID_STATE',
  MEDIA_STREAM_NOT_ALLOWED = 'MEDIA_STREAM_NOT_ALLOWED',
  MEDIA_STREAM_NOT_FOUND = 'MEDIA_STREAM_NOT_FOUND',
  MEDIA_STREAM_NOT_READABLE = 'MEDIA_STREAM_NOT_READABLE',
  MEDIA_STREAM_OVERCONSTRAINED = 'MEDIA_STREAM_OVERCONSTRAINED',
  MEDIA_STREAM_SECURITY = 'MEDIA_STREAM_SECURITY',
  MEDIA_STREAM_TYPE = 'MEDIA_STREAM_TYPE',
  MEDIA_STREAM_UNSET = 'MEDIA_STREAM_UNSET',

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

  CREATE_MEDIA_STREAM_ARGS_UNSET = 'CREATE_MEDIA_STREAM_ARGS_UNSET',
  EXCEPTION = 'EXCEPTION',
  RUNTIME_VIOLATION = 'RUNTIME_VIOLATION',
  SYMBOL_DESCRIPTION_UNSET = 'SYMBOL_DESCRIPTION_UNSET',

  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'
}

Error reference

Error

Description

FRAME_RESULTS_SET_UNSET

Internal error; contact Support

OPTIONS_UNSET

Internal error; contact Support

VIDEO_ELEMENT_UNSET

Invalid state error, createKeylessVideoElement was called before createKeylessMediaStream

VIDEO_ELEMENT_EVENT_LISTENERS_UNSET

Internal error; contact Support

WEB_SOCKET_MESSAGE_SET_UNSET

Internal error; contact Support

USER_LOCKED_OUT

The user is locked out on their client device

MEDIA_DEVICES_EMPTY_VIDEO_INPUT_LABEL

The user did not grant permission to use the camera

MEDIA_DEVICES_NO_VIDEO_INPUTS

The user’s device does not have a camera

MEDIA_STREAM_ABORT

An AbortError exception occurred when attempting to retrieve media data from the user’s device. Learn more about AbortError exceptions in Mozilla’s MediaDevice.getUserMedia() reference page.

MEDIA_STREAM_INVALID_STATE

An InvalidStateError exception occurred when attempting to retrieve media data from the user’s device. Learn more about InvalidStateError exceptions in Mozilla’s MediaDevice.getUserMedia() reference page.

MEDIA_STREAM_NOT_ALLOWED

A NotAllowed exception occurred when attempting to retrieve media data from the user’s device. Learn more about NotAllowedError exceptions in Mozilla’s MediaDevice.getUserMedia() reference page.

MEDIA_STREAM_NOT_FOUND

A NotFoundError exception occurred when attempting to retrieve media data from the user’s device. Learn more about NotFoundError exceptions in Mozilla’s MediaDevice.getUserMedia() reference page.

MEDIA_STREAM_NOT_READABLE

A NotReadableError exception occurred when attempting to retrieve media data from the user’s device. Learn more about NotReadableError exceptions in Mozilla’s MediaDevice.getUserMedia() reference page.

MEDIA_STREAM_OVERCONSTRAINED

An OverconstrainedError exception occurred when attempting to retrieve media data from the user’s device. Learn more about OverconstrainedError exceptions in Mozilla’s MediaDevice.getUserMedia() reference page.

MEDIA_STREAM_SECURITY

A SecurityError exception occurred when attempting to retrieve media data from the user’s device. Learn more about SecurityError exceptions in Mozilla’s MediaDevice.getUserMedia() reference page.

MEDIA_STREAM_TYPE

A TypeError exception occurred when attempting to retrieve media data from the user’s device. Learn more about TypeError exceptions in Mozilla’s MediaDevice.getUserMedia() reference page.

MEDIA_STREAM_UNSET

Integration error. The createKeylessVideoElement function must be called after createKeylessVideoStream.

SERVER_CUSTOMER_NOT_FOUND

The customer does not exist. Contact Support.

SERVER_FACE_DOES_NOT_MATCH

The face captured during the stream does not match the one enrolled

SERVER_FORBIDDEN

The authorization token is invalid

SERVER_IMAGE_ENCRYPT_FAILED

Internal error; contact Support

SERVER_INTERNAL_ERROR

Internal error; contact Support

SERVER_NO_ATTEMPTS_LEFT

The user used all available circuits, authentication cannot proceed without a new enrollment

SERVER_RECOGNITION_FAILED

Biometric error. Contact Support

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

Internal error; contact Support

SERVER_USER_ALREADY_ENROLLED

The user is attempting to enroll a username that is already enrolled

SERVER_USER_NOT_FOUND

The user is attempting to authenticate with a user that is not enrolled

SERVER_USER_LOCKED_OUT

The user is locked out of the server.

SERVER_VALIDATION_FAILED

Internal error; contact Support

SESSION_MANAGER_NOT_NULL

Integration error. The attempt must complete or be disposed using deleteKeylessAuth or deleteKeylessEnroll. Otherwise, calling createKeylessAuth or createKeylessEnroll triggers this error

SESSION_MANAGER_NULL

Integration error. The createKeylessAuth or createKeylessEnroll functions must be called before using createKeylessVideoStream, createKeylessVideoElement or openKeylessWebSocketConnection.

This error also occurs when you don’t have the proper security headers to run Web Assembly in your server. Learn more in Security headers.

CREATE_MEDIA_STREAM_ARGS_UNSET

Internal error; contact Support

EXCEPTION

Generic web assembly error. Contact Support.

RUNTIME_VIOLATION

Tampering detected. Contact Support.

SYMBOL_DESCRIPTION_UNSET

Internal error; contact Support

SESSION_ID_UNSET

Internal error; contact Support

CUSTOMER_UNSET

Integration error. The customer.name option is either undefined or empty

KEY_DECODE_FAILED

Integration error. The key.value option can’t be decoded.

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. Contact Support.

WEB_ASSEMBLY_FACTORY_FAILED

The web assembly initialization failed. Contact Support.

WEB_ASSEMBLY_IMPORT_FAILED

The web assembly import failed. Contact Support.

WEB_ASSEMBLY_NOT_READY

Integration error. The importKeylessWebAssemblyModule was not called before using other APIs.

WEB_ASSEMBLY_MODULE_NOT_FOUND

Internal error; contact Support

WEB_SOCKET_ERROR

Connection error. Contact Support.

WEB_SOCKET_OPEN

Connection error. Contact Support.

WEB_SOCKET_TIMEOUT

The server took too long to reply to the client

WEB_SOCKET_UNEXPECTED_CLOSE

Either a connection or internal error. Contact Support.

Web component error handling

Web components inherit errors from the @keyless/sdk-web library. Use the Error reference to diagnose errors in web components.

The following example shows how to handle an error event within a <kl-auth> web component:

Details

<!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
      authorization-token="USER_AUTHORIZATION_FROM_CUSTOMER"
      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="@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>

The SDK extends the ErrorEvent to provide the error code inside the error message and to include additional errors:

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

  NONCANCELABLE = 'NONCANCELABLE'
}

Each KeylessComponentsError error represents an internal error. Contact Support.