Error Handling
When authentication fails, the SDK returns a VeryResult with isSuccess = false
and an errorType indicating what went wrong.
Where to read the code#
Two fields on VeryResult are easy to confuse:
-
error— the numeric code below, as a string ("6101"). This is the one to branch on. In React Native it is the only form available. -
code— an outcome label, one of"success","error", or"cancelled". Despite the name it never holds a numeric code.
On iOS and Android, errorType resolves error into the typed enum in the
table below.
Error types#
| Error Type | Code | What happened | What to do |
|---|---|---|---|
cameraPermissionDenied | 6101 | Camera access not granted | Prompt the user to enable camera permission in Settings. |
captureFailed | 6102 | Palm capture failed (camera/processing error) | Retry. Suggest better lighting and holding the hand steady. |
sessionExpired | 6103 | SDK session timed out | Call authenticate() again to start a new session. |
userCanceled | 6104 | User dismissed the SDK | No action needed. The user chose to go back. |
missingCameraUsageDescription | 6105 | iOS only — the host app's Info.plist has no NSCameraUsageDescription | Add the key and rebuild. A JS reload or app restart will not pick it up. Android has no equivalent; it uses the runtime permission model instead. |
noInternet | 6001 | No connection — offline, airplane mode, or server unreachable | Ask the user to check their connection, then retry. |
timeout | 6002 | Network request timed out | Retry. Check network connectivity. |
dnsError | 6003 | Our servers could not be resolved — captive portal or DNS issue | Suggest switching networks. Common on hotel and airport Wi-Fi. |
networkError | 6004 | Connection dropped, refused, or interrupted | Retry. |
tlsError | 6005 | Secure connection failed | Usually a wrong device clock. Ask the user to check date & time. |
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. |
serverError | 6006 | Unexpected server error — also the fallback for any code not listed above | Retry. If persistent, report to VeryAI support with the raw error value. |
Restricted account states#
When a user's account is restricted, 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.
These states are not members of errorType. They arrive as raw
values in result.error, and because the typed enum does not cover them,
errorType reports them as serverError. Branch on the string if you
need to tell them apart:
result.error | What happened | What to do |
|---|---|---|
"5010" | Account was permanently rejected | Direct the user to contact support. Retrying will not help. |
"5011" | Account enrollment is under review | The user should wait for review to complete. |
"5012" | Re-enrollment attempted but review is not rejected | The user's enrollment is still valid. Use verification instead of enrollment. |
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 13.0 or later
- Android: Android 6.0 (API level 23, Marshmallow) or later with at least 1GB RAM; 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.
