Skip to Content
GuidesHandle failure modes

Handle failure modes

A single catch block is not enough. Different error classes mean different recovery actions. Use the class hierarchy.

Full example

import { SladeIDError, CaptureError, QualityError, NetworkError, EncryptionError, AuthError, } from '@sladeid/slade-id-sdk'; try { const result = await sdk.matchFace('subject-123', captureResult); } catch (err) { if (err instanceof AuthError) { // Refresh the ClientSecret and retry once. await refreshAuth(); return retry(); } if (err instanceof NetworkError) { // Transient: retry with backoff. return retryWithBackoff(); } if (err instanceof QualityError) { // Recapture with relaxed thresholds or better lighting. return promptRecapture(); } if (err instanceof CaptureError) { // Camera or browser issue. Specific code determines recovery. return handleCaptureError(err); } if (err instanceof EncryptionError) { // Environment can't run Web Crypto. Cannot recover at runtime. return surfaceFatalError(err); } if (err instanceof SladeIDError) { // Catch-all for configuration errors. return surfaceFatalError(err); } throw err; }

Recovery patterns

  • AuthError — refresh the ClientSecret and retry once. Do not retry on a second AuthError from the same token.
  • NetworkError — exponential backoff with a cap. Three retries is usually enough; more risks frustrating the user. Surface a “try again” UI after the cap.
  • QualityError — recapture is the only fix. Show guidance to the user and start a new session.
  • CaptureError — branch on code. Permission denial, no camera, and capture-failed each need different UX.
  • EncryptionError — fatal at runtime. The environment lacks Web Crypto. Confirm the page is on HTTPS or localhost.
  • SladeIDError — usually a configuration mistake caught at integration time. Fix and redeploy.

See also