Result codes and resolutions

For a list of methods that could throw a specific result code, refer to Enum ResultType in the Client API Docs.

ALREADY_INITIALIZED

The App SDK has already been initialized. This result code can be returned by the production installation of the application.

Resolution

You can ignore this result code.

APP_NOT_FOUND

• UAF Apps: This result code rarely occurs because it is only returned for a standalone FIDO Client, not for an embedded Client. The app's facet ID could not be found in the file facets.uaf, which is hosted on your server.

• FIDO2 Apps: The app wasn't added to the Authentication Server or the app's package name and SHA256 fingerprints of the app's signing certificate are missing from the file assetlinks.json.

Corresponding UAF error code: UNTRUSTED_FACET_ID

Corresponding FIDO2 error: SECURITY_ERR

Resolutions

• UAF App: Add the app's facet ID to facets.uaf. Refer to Configure apps section Update facets.uaf.

• FIDO2 App:

  • Verify that you added the app using the Server Admin Console. Refer to Configure apps.

  • Check that the app's package name and SHA256 fingerprints of its signing certificate are in assetlinks.json. Refer to FIDO2 section Creating Your Digital Asset Links File.

AUTHENTICATOR_ACCESS_DENIED

The authenticator denied access to the resulting request. The authenticator returns this result code if any unexpected condition happens. It is unlikely that this result will be returned in production.

Resolution

Check the logs and configuration, this could also be due to a coding error. Display an error to the user and ask them to reregister.

AUTHENTICATOR_UNAVAILABLE

The authenticator is not available. This is returned during registration or authentication. Can be returned by the production installation of the application.

Resolution

Inform the user that the authenticator is not available. The user may enable the authenticator and attempt authentication again. For example, this error can be triggered if the Verify it's you in Apps option on a Pixel device running Android 13 is switched off. The user can switch the option on and perform the failed authentication again.

BAD_SESSION

There is a problem with the session, most likely it has expired.

Resolution

Ask the user to sign in again so they can get a new session.

CANCELED

The user canceled the registration, authentication, or transaction confirmation operation. You could see this error in production.

Resolution

You can ignore this result code because the user initiated the action.

CONNECTION_ERROR

The App SDK cannot connect to any servers due to a network issue. This result code can be returned by the production installation of the application.

Corresponding FIDO2 error code: NETWORK_ERR (Google Play Services only)

Resolution

Verify that you are connected to the internet. Double check that the server URLs are correct. Display an error to the user warning them that the internet connection failed and they should retry connecting.

CONSTRAINT_ERROR

The user's FIDO2 authenticator does not match the settings for FIDO2 authenticator attributes in your FIDO policy. This specifically applies to the authenticator attributes Require Resident Key or User Verification. See Create a FIDO policy for FIDO2 authenticators.

Corresponding FIDO2 error code: CONSTRAINT_ERR

Resolution

Check the FIDO policy against the user's available FIDO2 authenticators. Relax the policy if necessary or update your authenticator.

ENCODING_ERROR

An encoding or decoding operation for a Base 64 message failed. This result code occurs only for FIDO2 apps.

Corresponding FIDO2 error code: ENCODING_ERR

Resolution

Examine your source code to determine the cause of the message corruption.

FAILURE

The operation failed for a non-specific reason. This is a generic catch-all error. You could see this result code during production.

When a Pixel 7 Pro user attempts a login after receiving a USER_LOCKOUT for too many failed attempts, the system returns FAILURE.

Corresponding UAF error code: UNKNOWN

Corresponding FIDO2 error code: UNKNOWN_ERR

Resolution

Try examining the client and server logs as well as obtaining a reproducible case with more information. Display an error to the user.

FALLBACK

If an authenticator supports the authentication fallback option, it displays a button, labeled Use Alternate Authentication, that the user can tap to sign in with an alternate method, like username and password. If the user taps this button, this result code is returned. FALLBACK only applies to UAF authenticators.

Resolution

In response to this result code, your application should perform an alternate authentication mechanism (such as a prompt for a PIN).

INVALID_QR

The App SDK was unable to decode the QR bitmap into a text string or the resulting string is missing mandatory fields.

Resolution

Check the OOB configuration on the Authentication Server. See Out-of-band section Step1.Configure the Server.

INVALID_SERVER_RESPONSE

The response from the server could not be processed. This could be due to problems parsing JSON or base64 as well as missing parameters in the response.

Resolution

Examine your source code to determine the cause of the problem.

INVALID_STATE

The user tried to register an authenticator on the device which has already been registered

Corresponding FIDO2 error code: INVALID_STATE_ERR

KEY_DISAPPEARED_PERMANENTLY

This result code can occur during authentication or transaction confirmation. On Android, it happens after the user adds a fingerprint. This error also occurs after all fingerprints have been deleted from the device. This result code can be returned by the production installation of the application.

For certain FIDO authenticators, like Fingerprint, when biometric templates are added or removed, existing FIDO registrations are invalidated which is why this error occurs during authentication or transaction confirmation. See Error Handling for the Native Fingerprint ASM for details. Refer to the description of the specific authenticator you are using to determine when or if FIDO registrations are invalidated.

Corresponding UAF error code: KEY_DISAPPEARED_PERMANENTLY.

Resolution

Display the error to the user and have them reregister.

NO_MATCH

This error occurs during registration, authentication, or transaction confirmation. During registration it occurs when the user's device has no available authenticators to register that match the registration policy. During authentication or transaction confirmation, it occurs when the user has no registered authenticators to authenticate with that match the FIDO policy from the succeeding Authentication Rule. This error can be returned by the production installation of the application.

Corresponding UAF error code: NO_SUITABLE_AUTHENTICATOR

Corresponding FIDO2 error code: NOT_ALLOWED_ERR

Resolution

Check if the user can possibly register, authenticate, or confirm a transaction before calling the methods to register, authenticate, or confirm the transaction. Call the checkRegPossible(), checkAuthPossible(), or checkTransPossible() methods, as appropriate. These check* methods attempt to perform the FIDO operation.

Your application should display an error to the user.

Registration: Warn them that there are no available authenticators to register. This error is expected if all available authenticators are registered. If there are available authenticators that are not registered, review the FIDO policy to confirm that the available authenticators match what the policy specifies.

Authentication or Transaction Confirmation: Warn the user that there are no registered authenticators that they can use to authenticate or confirm the transaction. This error is expected if the user has not registered an authentication method required by the matching Authentication Rule to complete verification.

NOT_COMPATIBLE

The installed version of the FIDO Client is not compatible with your App SDK. This error is only returned for a standalone Client, not an embedded Client.

Corresponding UAF error code: UNSUPPORTED_VERSION

Corresponding FIDO2 error code: NOT_SUPPORTED_ERR, HMS_FRAMEWORK_ERR (HMS only)

Resolution

Install the correct version of the client that is compatible with your App SDK.

NOT_INSTALLED

The FIDO Client is not installed. Returned only for a standalone client, not an embedded client.

Resolution

Install the appropriate Client.

PROTOCOL_ERROR

This error occurs when the FIDO protocol is violated. Returned only if either the Auth Server or the Client is programmed incorrectly. When this happens, the Client cannot parse the message sent by the Auth Server.

End users should not encounter this error, this only occurs during the development phase.

Corresponding UAF error code: PROTOCOL_ERROR

Corresponding FIDO2 error code: DATA_ERR

Resolution

Examine the logs and look for coding errors.

SERVER_ERROR

This is a generic error sent by the FIDO server. It is used in situations that are not covered by SERVER_REG_NOT_FOUND, SERVER_USER_NOT_FOUND, or SERVER_UVI_NOT_MATCH. This error can occur in production.

Resolution

Check the logs on the Server side. Display the error to the user. Maps to a 4403 error (FIDO policy verification exception or FIDO policy exception).

SERVER_REG_NOT_FOUND

The Auth Server found the user but was unable to find a registered UAF or FIDO2 authenticator for that user. This result code can occur in production.

Corresponds to the UAF error: UAF_REG_NOTFOUND_STATUS_CODE

Resolution

Register the user. Display the error to the user warning them that their registration was not found and they need to register.

SERVER_USER_NOT_FOUND

The Auth Server can't find the user. This result code can occur in production.

Corresponding UAF error: UAF_NO_REGISTRATIONS_STATUS_CODE

Resolution

Register the user. Display an error to the user, warning them that they are not registered and they need to register.

SERVER_UVI_NOT_MATCH

The UVI provided during authentication doesn't match the UVI provided during registration. This error corresponds to the UAF_UVI_NOT_MATCH_STATUS_CODE server error. This error only applies when the following authenticators are used:

• Fingerprint on a Sony device

• Fingerprint on the Sharp Aquos

• Fingerprint using the Samsung FIDO Client on a Samsung device

This error can occur in production.

Resolution

Use the correct UVI or register and update the pending UVI entry. Display an error to the user, warning them that they need to reregister.

SERVER_VERIFICATION_ERROR

Adaptive authentication or transaction confirmation failed or will fail because the user does not have any authentication methods that can be used to complete the operation. This error is based on the “Policy Verification Failed” (code 4403) error returned from the Auth Server.

Resolution

If the user should have been successfully authenticated, check the conditions and authentication sequences in your adaptive rules.

SUCCESS

The operation completed successfully. No resolution necessary.

SYSTEM_CANCELED

The system canceled the operation. This typically occurs when the application is moved to the background. For example, the user taps the home button or brings another application to the foreground.

SYSTEM_CANCELED is also returned when a biometric prompt times out before the operation can be completed.

Corresponding FIDO2 error code: ABORT_ERR

Resolution

You can ignore this result code.

USER_LOCKOUT

The user exceeded the maximum allowed attempts to enter credentials.

Resolution

Wait the prescribed amount of time (typically 4 minutes on Android) until user enrollment is available again. Display an error to the user warning them that registration is locked because of too many failed attempts. They need to reregister or wait a certain period of time until the authenticator is available again.

USER_NOT_ENROLLED

The user is not enrolled on the device. This result code is returned during registration if there is no enrollment on the device. Can be returned by the production installation of the application.

Resolution

The user needs to enroll on their device before they can register an authenticator. Display an error to the user, warning them that there's no enrollment on the device and they need to enroll before registration.

USER_NOT_RESPONSIVE

The user took too long to register, authenticate, or confirm a transaction.

Corresponding FIDO2 error code: TIMEOUT_ERR

Resolution

Let the user know the operation timed out. Have the user retry the operation.