Error Handling
The KeylessAuth
and KeylessEnroll
classes emit 2 kind of error events:
The all purpose
"error"
eventThe 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
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
Was this helpful?