Error handling

All error handling for the Android SDK is centralized in this section. The onErrorAcessoBio callback receives an ErrorBio object with code and description.

Error codes

Code	Default message	When it occurs	Recommended handling
AUTH_FAILED	SDK authentication failed	Invalid or expired SDK Key	Validate credentials with the Onboarding team
CAMERA_PERMISSION_DENIED	Camera permission denied	User denied camera permission	Direct the user to app settings
LIVENESS_FAILED	Liveness check failed	Image did not pass liveness validation	Request a new capture
NETWORK_ERROR	Network error during capture	Insufficient connectivity	Request reconnection
SDK_NOT_INITIALIZED	SDK not initialized	Capture called before init	Ensure init is called in Application/onCreate

SDK error codes

The codes above cover the primary SDK callback errors. REST API error codes (HTTP status families) are documented separately at API Reference > Error codes.

Handling the callback

Kotlin

override fun onErrorAcessoBio(error: ErrorBio) {
  when (error.code) {
    "AUTH_FAILED" -> { /* handle authentication failure */ }
    "CAMERA_PERMISSION_DENIED" -> { /* redirect to app settings */ }
    "LIVENESS_FAILED" -> { /* prompt the user to try again */ }
    else -> { /* generic error handling */ }
  }
}

Java

@Override
public void onErrorAcessoBio(ErrorBio error) {
  switch (error.getCode()) {
    case "AUTH_FAILED": /* handle authentication failure */ break;
    case "CAMERA_PERMISSION_DENIED": /* redirect to app settings */ break;
    case "LIVENESS_FAILED": /* prompt the user to try again */ break;
    default: /* generic error handling */
  }
}

Lifecycle callbacks

In addition to onErrorAcessoBio, the SDK also triggers:

• onUserClosedCameraManually() — user closed the camera manually.
• onSystemClosedCameraTimeoutSession() — session expired due to timeout.
• onSystemChangedTypeCameraTimeoutFaceInference() — no face detected for 13 seconds; the SDK switches to manual capture.