Errors
All errors extend SladeIDError and carry a code: string field. Catch by class for broad recovery, branch on code for specifics.
Core errors
| Class | Code | Thrown when | Recovery |
|---|---|---|---|
SladeIDError | CONFIG_INVALID | Required config missing (e.g. middlewareUrl) | Fix config |
SladeIDError | CONFIG_NOT_SUPPORTED | encryptBiometrics.face set true (unsupported in V0) | Drop the option |
SladeIDError | BAD_REQUEST | Backend returned a 4xx the SDK didn’t map (no code in body) | Fix the request |
CaptureError | CAMERA_PERMISSION_DENIED | User blocked or dismissed the camera prompt | Surface a permission UI; see the camera guide |
CaptureError | CAMERA_NOT_FOUND | No camera device is present | Ask the user to connect a camera |
CaptureError | CAMERA_IN_USE | Camera is held by another app or tab | Ask the user to close the other consumer |
CaptureError | CAMERA_ACCESS_FAILED | getUserMedia failed for another reason | Retry; verify the device |
CaptureError | SESSION_ALREADY_STARTED | start() called twice | Call stop() first |
CaptureError | NOT_IMPLEMENTED_V0 | Active liveness challenges configured | Active challenges are not implemented; omit activeChallenges |
CaptureError | NO_CAMERA | Capture attempted before the camera stream was ready | Wait for 'started' |
CaptureError | NO_CANVAS_CTX | Canvas 2D context unavailable | Verify the environment supports <canvas> |
CaptureError | CAPTURE_FAILED | canvas.toBlob returned null, or capture canceled | Retry |
QualityError | FACE_QUALITY_EXHAUSTED | Max face-quality retries exceeded | Improve lighting, framing |
NetworkError | TIMEOUT | Backend took longer than timeoutMs | Retry; bump timeoutMs if justified |
NetworkError | NETWORK_FAILURE | fetch rejected (DNS, CORS, offline) | Check connectivity, CORS config |
NetworkError | SERVER_ERROR | Backend returned a 5xx | Retry; escalate with X-SDK-Version |
NetworkError | NON_JSON_RESPONSE | A 2xx body wasn’t valid JSON | Check the backend / any proxy in front of it |
AuthError | UNAUTHORIZED | Backend returned 401 | Token expired or rejected; backend mints a fresh one, SDK re-requests via getToken() |
AuthError | FORBIDDEN | Backend returned 403 | Check the token’s scope / roles |
EncryptionError (codes NO_WEB_CRYPTO, NO_BASE64) is forward-compat only; face payloads are sent as plaintext base64 via NoopEncryptor. In V0 a missing base64 codec surfaces as a SladeIDError/CaptureError with code NO_BASE64, not an EncryptionError.
Fingerprint reader errors
Thrown by the fingerprint reader client. All extend HwsError and carry an optional correlationId field for support tickets.
| Class | Code | Thrown when |
|---|---|---|
ConnectionError | READER_CONNECTION_FAILED | The local hardware service is unreachable (companion app not running). |
TimeoutError | READER_TIMEOUT | No finger was presented within the capture window. |
ReaderAuthError | READER_AUTH_FAILED | The bearer was rejected, or getToken threw / returned empty. |
DeviceUnavailableError | READER_DEVICE_UNAVAILABLE | No scanner is available, or no workstation could be resolved. |
ReaderValidationError | READER_VALIDATION_FAILED | The request was rejected — bad input, or verify() with no enrolled template. |
DuplicateEnrollmentError | READER_DUPLICATE_TEMPLATE | enroll() on a finger that already has a live record. Subclasses ReaderValidationError, so existing instanceof handling still matches; the narrower code is what lets you branch without reading the message. |
ReaderServerError | READER_SERVER_ERROR | The validator or database was unavailable while matching. |
BiometricMismatchError | READER_BIOMETRIC_MISMATCH | Rejection-style helpers only; plain verify() resolves { matched: false }. |
HwsError | READER_DISPOSED | An action was called after dispose(). |
HwsError | READER_CANCELLED | A session was cancelled before its job was dispatched. |
HwsError | READER_SESSION_REUSED | start() called twice on a single-shot session. |
HwsError | READER_EMPTY_TEMPLATE | testCapture() came back with no template. |
A failed biometric match is not an error: verify() resolves { matched: false } and search() resolves { found: false }.
And note that not every reader failure is an HwsError. Enroll, verify, and search are dispatched over the shared middleware transport, so an HTTP-level refusal surfaces as a NetworkError or AuthError from the core table above — most commonly NetworkError / SERVER_ERROR carrying Middleware returned 503: Target workstation is not currently live. when the target workstation is offline. SladeIDError is the common ancestor of both families.