Result codes and resolutions

The App SDK returns the following result codes from many of its API calls using the enum FidoStatus. For a list of methods that could throw a specific result code, refer to enum nnl::appsdk::FidoStatus in the Client API Docs.

APP_NOT_FOUND

The application facet ID is not listed in the manifest file at the relying party. APP_NOT_FOUND Corresponds to an UNTRUSTED_FACET_ID UAF error. This error is returned only for a standalone Client, not for an embedded Client.

Resolution

Update the facet ID in the manifest file at the relying party.

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 error because the user initiated the action.

CONNECTION_ERROR

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

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.

FAILURE

The operation failed for some non-specific reason. This is a generic catch-all error. In the case of UAF, this corresponds to the UNKNOWN error. You could see this error during production.

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 fallback, it displays a button labeled Use Alternate Authentication. If the user taps this button, this result code is returned.

Resolution

In response to this error, 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

Review the OOB configuration on the Authentication Server. See Out-of-band, Step1.Configure the Auth Server.

INVALID_SERVER_RESPONSE

The response from the server could not be processed. This includes 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.

KEY_DISAPPEARED_PERMANENTLY

This error can occur during authentication or transaction confirmation. On iOS, it happens after the user adds or removes a fingerprint. This error also occurs after all fingerprints have been deleted from the device. This error 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. 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 re-register.

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

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.

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 Client is not compatible with your App SDK. This error is only returned for a standalone Client, not an embedded Client.

Resolution

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

NOT_INSTALLED

The FIDO Client is not installed. This only applies to a standalone Client, not an embedded Client.

Resolution

Install the appropriate FIDO 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 Server.

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

Corresponding UAF error code: PROTOCOL_ERROR

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_REGISTRATION_NOT_FOUND

The Server returns this error when it can’t find a registration. SERVER_REGISTRATION_NOT_FOUND corresponds to the UAF_REG_NOTFOUND_STATUS_CODE server error. This error can occur in production.

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 Server returns this error when it can’t find the user. SERVER_USER_NOT_FOUND corresponds to the UAF_NO_REGISTRATIONS_STATUS_CODE server error. This error can occur in production.

Resolution

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

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.

Resolution

You can ignore this error.

USER_LOCKOUT

The user exceeded the maximum allowed attempts to enter credentials

Resolution

Wait the prescribed amount of time 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 enrollment is available again.

USER_NOT_ENROLLED

The user is not enrolled on the device. This error is returned during registration if there is no enrollment in the system. Returned by the production installation of the application.

Resolution

Enroll the user in the system before registration. Display an error to the user, warning them that there's no enrollment on the device and they need to enroll before registration.