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

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

  SERVER_CUSTOMER_NOT_FOUND = 'SERVER_CUSTOMER_NOT_FOUND',
  SERVER_INTERNAL_ERROR = 'SERVER_INTERNAL_ERROR',
  SERVER_RECOGNITION_FAILED = 'SERVER_RECOGNITION_FAILED',

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

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

  SESSION_ID_UNSET = 'SESSION_ID_UNSET',

  CUSTOMER_UNSET = 'CUSTOMER_UNSET',
  USERNAME_UNSET = 'USERNAME_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',

  USER_LOCKOUT_EXPIRATION_UNSET = 'USER_LOCKOUT_EXPIRATION_UNSET'
  SERVER_INVALID_REQUEST = 'SERVER_INVALID_REQUEST'
  SERVER_INVALID_RESPONSE = 'SERVER_INVALID_RESPONSE'
  SESSION_DATABASE_ERROR = 'SESSION_DATABASE_ERROR'
  SESSION_MEDIA_STREAM_TIMEOUT = 'SESSION_MEDIA_STREAM_TIMEOUT'
  SESSION_MEDIA_STREAM_UNSET = 'SESSION_MEDIA_STREAM_UNSET'
  SERVICE_URL_PARSE_FAILED = 'SERVICE_URL_PARSE_FAILED'
  SERVICE_URL_UNSET = 'SERVICE_URL_UNSET'
  SLUG_UNSUPPORTED = 'SLUG_UNSUPPORTED'

}

Error reference

Error

Description

FRAME_RESULTS_SET_UNSET

Internal error; contact Support

OPTIONS_UNSET

Internal error; contact Support

WEB_SOCKET_MESSAGE_SET_UNSET

Internal error; contact Support

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.

SERVER_CUSTOMER_NOT_FOUND

The customer does not exist. Contact Support.

SERVER_INTERNAL_ERROR

Internal error; contact Support

SERVER_RECOGNITION_FAILED

Biometric error. Contact Support

SERVER_USER_LOCKED_OUT

The user is locked out of the server.

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.

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

USERNAME_UNSET

Integration error. The username 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.

USER_LOCKOUT_EXPIRATION_UNSET

Internal error; contact Support.

SERVER_INVALID_REQUEST

Internal error; contact Support.

SERVER_INVALID_RESPONSE

Internal error; contact Support.

SESSION_DATABASE_ERROR

Internal error; contact Support.

SESSION_MEDIA_STREAM_TIMEOUT

The user failed to pass the quality filters in time.

SESSION_MEDIA_STREAM_UNSET

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

SERVICE_URL_PARSE_FAILED

Integration error. The service.url option is not a valid URL.

SERVICE_URL_UNSET

Integration error. The service.url option is either undefined or empty.

SLUG_UNSUPPORTED

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
      lang="en"
      size="375"
      theme="light"
      transaction-data='DATA_FROM_CUSTOMER_SERVER_TO_BE_SIGNED'
      username="USERNAME"
      service-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',

}

Each KeylessComponentsError error represents an internal error. Contact Support.