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. |
emailNotVerified | 5015 | Email verification required before palm operations | Complete the email verification step before scanning palms. |
emailAlreadyVerified | 5016 | Email already verified for this session | No action needed — proceed to palm scan. |
accountRestricted | 5017 | Account restricted — blocked from all operations | The account has been flagged. Direct the user to support@very.org. |
emailFlowDisabled | 5018 | Email flow disabled for this session | Your app has email bypass enabled. The SDK skips email screens automatically — do not call email endpoints. |
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, 5017), 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.
Code 5017 is returned when enrollment, verification, or re-enrollment is attempted
on a restricted account. This check happens server-side on every request, so restrictions
take effect immediately — even mid-session.
Email bypass
If your app has email bypass enabled (contact VeryAI to set this up), the SDK skips the email
input and OTP verification screens entirely. If your integration accidentally calls the email
endpoints, the server returns error 5018 (emailFlowDisabled).
This is a configuration issue — the SDK handles it automatically when properly integrated.
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, 5017 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) with at least 6GB RAM
Use isSupported() to check before showing verification UI. The SDK fetches the latest requirements from the server, so these thresholds may be updated without an SDK update.
