Error Handling
When authentication fails, the SDK returns a VeryResult with isSuccess = false
and an errorType indicating what went wrong.
Error types
| Error Type | Code | What happened | What to do |
|---|---|---|---|
cameraPermissionDenied | 9001 | Camera access not granted | Prompt the user to enable camera permission in Settings. |
captureFailed | 9002 | Palm capture failed (camera/processing error) | Retry. Suggest better lighting and holding the hand steady. |
sessionExpired | 9003 | SDK session timed out | Call authenticate() again to start a new session. |
userCanceled | 9004 | User dismissed the SDK | No action needed. The user chose to go back. |
timeout | 9006 | Network request timed out | Retry. Check network connectivity. |
enrollmentFailed | 5003 | Palm registration failed (processing or fraud flag) | The user may retry. If persistent, the palm may be flagged for manual review. |
verificationExhausted | 5004 | All verification attempts used (max 3 per session) | Start a new session. Suggest removing gloves, cleaning the palm, better lighting. |
verificationFailed | 5005 | Palm didn't match the registered user | Prompt the user to try again. They have remaining attempts in the session. |
accountRejected | 5010 | Account was permanently rejected | The SDK shows a restricted screen automatically. Direct the user to contact support. |
accountPendingReview | 5011 | Account enrollment is under review | The SDK shows a "reviewing" screen. The user should wait for review to complete. |
reEnrollmentNotAllowed | 5012 | Re-enrollment attempted but review is not rejected | The user's enrollment is still valid. Use verification instead of enrollment. |
serverError | 0 | Unexpected server error | Retry. If persistent, report to VeryAI support. |
Restricted account states
When a user's account is restricted (codes 5010, 5011, 5012), the SDK automatically displays a restricted state screen. Your app does not need to build this UI — the SDK handles it. The user will see a message explaining their account status and how to contact support.
Best practices
- Check device support first — call
isSupported()before showing the verification option to avoid a bad experience on unsupported devices. - Handle cancellation gracefully —
userCanceledis not an error. Don't show an error message when the user simply goes back. - Guide on failure — for
verificationFailed, suggest better lighting, holding the hand steady, and keeping the palm flat. - Request camera permission early — request permission before calling the SDK, with a clear explanation of why it's needed.
- Retry on transient errors —
timeoutandserverErrorare often temporary. Offer a retry button. - Don't retry restricted states — codes 5010, 5011, 5012 are account-level states. Retrying won't help. Direct the user to support.
Device support
The SDK checks device compatibility automatically. The minimum requirements are:
- iOS: iOS 16.4 or later
- Android: Android 10 (API level 29) or later. 2-4GB RAM devices are supported; the SDK's runtime memory use is typically under 100MB.
Use isSupported() to check before showing verification UI. Current support checks include OS version, camera capability, and SDK runtime compatibility. The SDK fetches the latest requirements from the server, so these thresholds may be updated without an SDK update.
