Give users an actionable next step and keep diagnostics free of identity data.
Connect capture, processing and application review with a clear lifecycle.
Workflow events
Event
Recommended interface response
camera-ready
Show the requested side and alignment guide.
readability-check-started
Explain that the captured image is being checked.
front-captured
Pause capture and offer Scan back after the first side is read.
waiting-for-flip
Wait for the explicit handoff; do not imply the second side is finished.
back-captured
Show completion progress and prepare review.
quality-warning
Offer concise lighting, steadiness or positioning guidance.
recognition-feedback
Explain that the required information needs another clear capture.
Camera errors
Code
Action
CAMERA_HTTPS_REQUIRED
Use HTTPS, or localhost for local development.
CAMERA_DENIED
Ask the user to enable camera permission in browser settings and retry.
CAMERA_UNAVAILABLE
Check that a camera exists and another application is not holding it.
CAMERA_INTERRUPTED
Release the old stream and offer an explicit restart.
CAMERA_CAPTURE_TIMEOUT
Offer another capture with better positioning and lighting.
Runtime errors
Code
Action
SDK_DEVICE_UNSUPPORTED
Check browser capabilities; offer another supported device.
SDK_ASSET_INTEGRITY
Verify the complete versioned deployment. Do not bypass integrity checks.
SDK_ASSET_UNAVAILABLE
Check asset paths, HTTPS access and server responses.
OCR_TIMEOUT
Offer a bounded retry; inspect device load and runtime configuration.
SDK_CANCELLED
Treat cancellation of an obsolete run as expected cleanup.
SDK_PROCESSING_FAILED
Show a safe retry message and record sanitized diagnostic metadata only.
Safe observability
Record the SDK version, event code, side, bounded elapsed time and browser family when needed for diagnosis. Never record document images, extracted personal information, passwords, session cookies or recovery links in application logs. A technical error does not justify weakening acceptance policy.
