# 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:

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

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:

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

  USER_LOCKED_OUT = 'USER_LOCKED_OUT',

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

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

### Errors Explanation

| Error                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FRAME_RESULTS_SET_UNSET`               | Logic error, report to Keyless                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `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                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `MEDIA_STREAM_ABORT`                    | Read [MediaDevices: getUserMedia() Exceptions Reference](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions)                                                                                                                                                                                                                                                                                                                                                               |
| `MEDIA_STREAM_INVALID_STATE`            | Read [MediaDevices: getUserMedia() Exceptions Reference](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions)                                                                                                                                                                                                                                                                                                                                                               |
| `MEDIA_STREAM_NOT_ALLOWED`              | Read [MediaDevices: getUserMedia() Exceptions Reference](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions)                                                                                                                                                                                                                                                                                                                                                               |
| `MEDIA_STREAM_NOT_FOUND`                | Read [MediaDevices: getUserMedia() Exceptions Reference](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions)                                                                                                                                                                                                                                                                                                                                                               |
| `MEDIA_STREAM_NOT_READABLE`             | Read [MediaDevices: getUserMedia() Exceptions Reference](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions)                                                                                                                                                                                                                                                                                                                                                               |
| `MEDIA_STREAM_OVERCONSTRAINED`          | Read [MediaDevices: getUserMedia() Exceptions Reference](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions)                                                                                                                                                                                                                                                                                                                                                               |
| `MEDIA_STREAM_SECURITY`                 | Read [MediaDevices: getUserMedia() Exceptions Reference](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#exceptions)                                                                                                                                                                                                                                                                                                                                                               |
| `MEDIA_STREAM_TYPE`                     | Read [MediaDevices: getUserMedia() Exceptions Reference](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, 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`                  | <p>Integration error, the createKeylessAuth or createKeylessEnroll functions must be called before using createKeylessVideoStream, createKeylessVideoElement and openKeylessWebSocketConnection.<br><br>This error can also trigger if you don't have the proper security headers to run Web Assembly in your server, check out <a href="https://docs.keyless.io/web-sdk/web-sdk-guide/prerequisites#security-headers"><https://docs.keyless.io/web-sdk/web-sdk-guide/prerequisites#security-headers></a></p> |
| `EXCEPTION`                             | Generic web assembly error, report to Keyless                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `RUNTIME_VIOLATION`                     | Tampering detection, contact Keyless for more details                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `SYMBOL_DESCRIPTION_UNSET`              | Logic error, report to Keyless                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `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](#errors-explanation "mention")

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:

```html
<!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:

```typescript
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 |