--- title: Error handling description: "\"Explains the errors that can occur when using the PingOne Recognize Web SDK and how to handle them.\"" component: recognize page_id: recognize:web-sdk:web-sdk-reference-error-handling canonical_url: https://docs.pingidentity.com/recognize/web-sdk/web-sdk-reference-error-handling.html llms_txt: https://docs.pingidentity.com/recognize/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md section_ids: error-types: Error types registering-event-listeners: Registering event listeners handling-errors: Handling errors error-reference: Error reference web-component-error-handling: Web component error handling --- # 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: ```javascript 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: > **Collapse: Details** > > ```javascript > 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](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions). | | `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](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions). | | `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](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions). | | `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](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions). | | `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](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions). | | `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](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions). | | `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](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions). | | `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](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions). | | `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](web-sdk-prerequisites.html#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](#error-reference) to diagnose errors in web components. The following example shows how to handle an error event within a `` web component: > **Collapse: Details** > > ```javascript > > > > > > 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" > > > > > > > ``` The SDK extends the `ErrorEvent` to provide the error code inside the error message and to include additional errors: ```javascript enum KeylessComponentsError { QUEUE_UNSET = 'QUEUE_UNSET', SYMBOL_UNSET = 'SYMBOL_UNSET', NONCANCELABLE = 'NONCANCELABLE' } ``` Each `KeylessComponentsError` error represents an internal error. Contact Support.