Handle failure modes

The SDK never throws across the API boundary for operational failures. Capture methods return null and emit a typed SladeIDError on a flow. Handle each class deliberately.

Where errors surface

viewModelScope.launch {
    session.errors.collect { e ->
        when (e) {
            is AuthError     -> promptReauth()        // credentials rejected / gate
            is NetworkError  -> retryLater(e.httpStatus)
            is QualityError  -> promptBetterPlacement(e.finger)
            is CaptureError  -> promptReplaceReader()  // hardware/timeout
            is EncryptionError -> logAndAlert(e)
            else             -> logUnknown(e)
        }
    }
}

The error classes

• AuthError (AUTH_ERROR) — invalid/absent token, or the credential gate rejected the capture. The sensor was not activated. Fix credentials, then retry.
• NetworkError (NETWORK_ERROR) — Slade ID service unreachable, timeout, or HTTP error; carries httpStatus.
• QualityError (QUALITY_ERROR) — quality threshold not met; carries finger and score.
• CaptureError (CAPTURE_ERROR) — hardware/vendor failure or capture timeout.
• EncryptionError (ENCRYPTION_ERROR) — encryption key exchange failed.
• SladeIDError — base class; catch it last.

What is not an error

• match / search returning matched = false — a normal biometric result.
• verifyEnrollment returning positionVerified = false — a normal “try again” during enrollment.
• A reader not plugged in — never emitted on readerErrors; you observe an empty readers list.

Retry posture

• Auth — ClientCredentialsAuth refreshes proactively; on a hard 401 call invalidate() then retry once.
• Network — back off and retry; the SDK already retries once on a 401 after re-fetching headers.
• Quality / verify non-match — reprompt the user; these are expected.

Used in

• Capture lifecycle
• Errors reference
• Troubleshooting