Handle Firebase Phone Number Verification errors on Android

When a call to the Firebase PNV library fails, the library reports a FirebasePhoneNumberVerificationException. This page lists every error code that the exception can carry, when each one occurs, and what your app should do about it.

This page assumes you've integrated Firebase PNV as described in Get started with Firebase Phone Number Verification on Android.

How errors are reported

• Asynchronous methods (getVerificationSupportInfo(), getVerifiedPhoneNumber(), and the custom flow methods) return a Task. When they fail, the Task fails with a FirebasePhoneNumberVerificationException, which you receive in addOnFailureListener.

• enableTestSession() is synchronous. It throws a FirebasePhoneNumberVerificationException directly.

Read the exception's errorCode to find out what went wrong. The Firebase PNV codes are constants in the FirebasePnvStatusCodes class. If the failure comes from Google Play services, errorCode can also be a CommonStatusCodes value, such as NETWORK_ERROR.

An unsupported device or SIM isn't an error. getVerificationSupportInfo() succeeds and reports isSupported() as false for that SIM, and getReason() tells you why. See Unsupported devices and SIMs.

Error codes

Test session setup

These errors are thrown synchronously by enableTestSession().

Verification

These errors fail the Task returned by getVerifiedPhoneNumber().

Support check

The Task returned by getVerificationSupportInfo() fails only if the check itself can't run. In that case, errorCode is either a Google Play services CommonStatusCodes value or CARRIER_NOT_SUPPORTED. Treat the device as unsupported and fall back to another verification method, such as SMS.

While a test session is enabled, getVerificationSupportInfo() doesn't contact the Firebase PNV backend and always reports the test SIM as supported, even if the test token has expired.

Custom flow

If you use the custom flow instead of getVerifiedPhoneNumber():

• getDigitalCredentialPayload() fails with PREFLIGHT_CHECK_FAILED, or with INVALID_TEST_NUMBER_ID if the backend rejects your test token.
• exchangeCredentialResponseForPhoneNumber() fails with INVALID_DIGITAL_CREDENTIAL_RESPONSE, or with INVALID_TEST_NUMBER_ID if the backend rejects your test token.
• Your own call to Credential Manager throws a GetCredentialException, which you handle directly.

Unsupported devices and SIMs

When isSupported() is false for a SIM, getReason() returns one of the following VerificationSupportStatus values:

In each case, use another verification method, such as SMS, for that SIM.

Example

The following example handles the errors that a typical app needs to distinguish when calling getVerifiedPhoneNumber():

import android.util.Log
// Credential Manager is included with the Firebase PNV library.
import androidx.credentials.exceptions.GetCredentialCancellationException
import com.google.firebase.pnv.FirebasePhoneNumberVerification
import com.google.firebase.pnv.FirebasePhoneNumberVerificationException
import com.google.firebase.pnv.FirebasePnvStatusCodes

private const val TAG = "PhoneVerification"

// In your Activity:
private fun verifyPhoneNumber() {
    FirebasePhoneNumberVerification.getInstance()
        .getVerifiedPhoneNumber(this)
        .addOnSuccessListener { result ->
            // Send result.getToken() to your backend.
        }
        .addOnFailureListener { e -> handleFpnvError(e) }
}

private fun handleFpnvError(e: Exception) {
    if (e !is FirebasePhoneNumberVerificationException) {
        Log.w(TAG, "Firebase PNV failed", e)
        showSmsVerification()
        return
    }
    when (e.errorCode) {
        FirebasePnvStatusCodes.CREDENTIAL_MANAGER_ERROR -> {
            if (e.cause is GetCredentialCancellationException) {
                // The user dismissed the consent screen.
            }
            showSmsVerification()
        }
        FirebasePnvStatusCodes.INVALID_TEST_NUMBER_ID -> {
            // Test mode only: generate a new test token.
            Log.e(TAG, "Firebase PNV test token rejected", e)
        }
        FirebasePnvStatusCodes.ACTIVITY_CONTEXT_REQUIRED -> {
            // App bug: pass an Activity to getVerifiedPhoneNumber().
            Log.e(TAG, "Firebase PNV needs an Activity context", e)
        }
        else -> {
            // Carrier not supported, network errors, and other failures.
            Log.w(TAG, "Firebase PNV failed with error code ${e.errorCode}", e)
            showSmsVerification()
        }
    }
}

In this example, showSmsVerification() is your app's existing phone number verification flow.

Next steps

• For details about each class and constant, see the Firebase PNV API reference.
• To verify the token on your server, see Verify Firebase PNV tokens.