define app check specific client error codes

Author: yvonnep165

src/main/java/com/google/firebase/appcheck/AppCheckErrorCode.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.firebase.appcheck;
+
+/**
+ * Error codes that can be raised by the Firebase App Check APIs.
+ */
+public enum AppCheckErrorCode {
+
+  /**
+   * One or more arguments specified in the request were invalid.
+   */
+  INVALID_ARGUMENT,
+
+  /**
+   * The provided App Check token is invalid or malformed.
+   */
+  INVALID_APP_CHECK_TOKEN,
+
+  /**
+   * The provided App Check token has expired.
+   */
+  APP_CHECK_TOKEN_EXPIRED,
+
+  /**
+   * Internal error encountered during App Check token verification.
+   */
+  INTERNAL_ERROR,
+
+  /**
+   * App Check verification service is temporarily unavailable or returned an error.
+   */
+  SERVICE_ERROR,
+}

src/main/java/com/google/firebase/appcheck/FirebaseAppCheckException.java

@@ -28,28 +28,45 @@
  */
 public class FirebaseAppCheckException extends FirebaseException {
 
+  private final AppCheckErrorCode errorCode;
+
   public FirebaseAppCheckException(
       @NonNull ErrorCode errorCode,
       @NonNull String message,
       @Nullable Throwable cause,
-      @Nullable IncomingHttpResponse response) {
+      @Nullable IncomingHttpResponse response,
+      @Nullable AppCheckErrorCode appCheckErrorCode) {
     super(errorCode, message, cause, response);
+    this.errorCode = appCheckErrorCode;
+  }
+
+  public FirebaseAppCheckException(
+      @NonNull ErrorCode errorCode,
+      @NonNull String message,
+      @Nullable Throwable cause,
+      @Nullable IncomingHttpResponse response) {
+    this(errorCode, message, cause, response, null);
   }
 
   public FirebaseAppCheckException(
       @NonNull ErrorCode errorCode,
       @NonNull String message,
       @Nullable Throwable cause) {
-    this(errorCode, message, cause, null);
+    this(errorCode, message, cause, null, null);
   }
 
   public FirebaseAppCheckException(
       @NonNull ErrorCode errorCode,
       @NonNull String message) {
-    this(errorCode, message, null, null);
+    this(errorCode, message, null, null, null);
   }
 
   public FirebaseAppCheckException(@NonNull FirebaseException base) {
-    this(base.getErrorCode(), base.getMessage(), base.getCause(), base.getHttpResponse());
+    this(base.getErrorCode(), base.getMessage(), base.getCause(), base.getHttpResponse(), null);
+  }
+
+  @Nullable
+  public AppCheckErrorCode getAppCheckErrorCode() {
+    return errorCode;
   }
 }

src/main/java/com/google/firebase/appcheck/internal/AppCheckTokenVerifier.java

@@ -31,6 +31,7 @@
 import com.google.firebase.ErrorCode;
 import com.google.firebase.FirebaseApp;
 import com.google.firebase.ImplFirebaseTrampolines;
+import com.google.firebase.appcheck.AppCheckErrorCode;
 import com.google.firebase.appcheck.DecodedAppCheckToken;
 import com.google.firebase.appcheck.FirebaseAppCheckException;
 import com.google.firebase.appcheck.VerifyAppCheckTokenOptions;
@@ -146,22 +147,34 @@ private DecodedAppCheckToken verifyTokenLocally(String token) throws FirebaseApp
       return new DecodedAppCheckToken(claims.getClaims());
     } catch (ParseException e) {
       throw new FirebaseAppCheckException(
-          ErrorCode.INVALID_ARGUMENT, "Failed to parse App Check JWT token: " + e.getMessage(), e);
+          ErrorCode.INVALID_ARGUMENT,
+          "Failed to parse App Check JWT token: " + e.getMessage(),
+          e,
+          null,
+          AppCheckErrorCode.INVALID_APP_CHECK_TOKEN);
     } catch (ExpiredJWTException e) {
       throw new FirebaseAppCheckException(
-          ErrorCode.INVALID_ARGUMENT, "Firebase App Check token has expired.", e);
+          ErrorCode.INVALID_ARGUMENT,
+          "Firebase App Check token has expired.",
+          e,
+          null,
+          AppCheckErrorCode.APP_CHECK_TOKEN_EXPIRED);
     } catch (BadJOSEException e) {
       throw new FirebaseAppCheckException(
           ErrorCode.INVALID_ARGUMENT,
           "Check your project: " + projectId + ". Failed to verify App Check token signature: "
               + e.getMessage(),
-          e);
+          e,
+          null,
+          AppCheckErrorCode.INVALID_APP_CHECK_TOKEN);
     } catch (JOSEException e) {
       throw new FirebaseAppCheckException(
           ErrorCode.INTERNAL,
           "Check your project: " + projectId + ". Internal error processing App Check token: "
               + e.getMessage(),
-          e);
+          e,
+          null,
+          AppCheckErrorCode.INTERNAL_ERROR);
     }
   }
 
@@ -172,17 +185,27 @@ private void verifyHeader(JWSHeader header) throws FirebaseAppCheckException {
           "App Check token has incorrect algorithm. Expected "
               + JWSAlgorithm.RS256.getName()
               + " but got: "
-              + header.getAlgorithm());
+              + header.getAlgorithm(),
+          null,
+          null,
+          AppCheckErrorCode.INVALID_APP_CHECK_TOKEN);
     }
     if (Strings.isNullOrEmpty(header.getKeyID())) {
       throw new FirebaseAppCheckException(
-          ErrorCode.INVALID_ARGUMENT, "App Check token has no 'kid' (key ID) header.");
+          ErrorCode.INVALID_ARGUMENT,
+          "App Check token has no 'kid' (key ID) header.",
+          null,
+          null,
+          AppCheckErrorCode.INVALID_APP_CHECK_TOKEN);
     }
     if (header.getType() == null || !JOSEObjectType.JWT.equals(header.getType())) {
       throw new FirebaseAppCheckException(
           ErrorCode.INVALID_ARGUMENT,
           "App Check token has incorrect 'typ' header. Expected JWT but got: "
-              + header.getType());
+              + header.getType(),
+          null,
+          null,
+          AppCheckErrorCode.INVALID_APP_CHECK_TOKEN);
     }
   }
 
@@ -192,7 +215,11 @@ private void verifyClaims(JWTClaimsSet claims) throws FirebaseAppCheckException
 
     if (Strings.isNullOrEmpty(issuer)) {
       throw new FirebaseAppCheckException(
-          ErrorCode.INVALID_ARGUMENT, "App Check token has no 'iss' (issuer) claim.");
+          ErrorCode.INVALID_ARGUMENT,
+          "App Check token has no 'iss' (issuer) claim.",
+          null,
+          null,
+          AppCheckErrorCode.INVALID_APP_CHECK_TOKEN);
     }
 
     // The issuer is of the form https://firebaseappcheck.googleapis.com/<project_number>.
@@ -207,7 +234,10 @@ private void verifyClaims(JWTClaimsSet claims) throws FirebaseAppCheckException
           "App Check token has incorrect issuer. Expected to start with: "
               + APP_CHECK_ISSUER
               + " but got: "
-              + issuer);
+              + issuer,
+          null,
+          null,
+          AppCheckErrorCode.INVALID_APP_CHECK_TOKEN);
     }
 
     List<String> audience = claims.getAudience();
@@ -218,12 +248,19 @@ private void verifyClaims(JWTClaimsSet claims) throws FirebaseAppCheckException
           "App Check token has incorrect audience. Expected to contain: "
               + expectedAudience
               + " but got: "
-              + audience);
+              + audience,
+          null,
+          null,
+          AppCheckErrorCode.INVALID_APP_CHECK_TOKEN);
     }
 
     if (Strings.isNullOrEmpty(claims.getSubject())) {
       throw new FirebaseAppCheckException(
-          ErrorCode.INVALID_ARGUMENT, "App Check token has empty 'sub' (app ID) claim.");
+          ErrorCode.INVALID_ARGUMENT,
+          "App Check token has empty 'sub' (app ID) claim.",
+          null,
+          null,
+          AppCheckErrorCode.INVALID_APP_CHECK_TOKEN);
     }
   }
 
@@ -260,7 +297,11 @@ private boolean verifyOneTimeToken(String token)
       return Boolean.TRUE.equals(alreadyConsumed);
     } catch (IOException e) {
       throw new FirebaseAppCheckException(
-          ErrorCode.INTERNAL, "Error verifying App Check token with backend: " + e.getMessage(), e);
+          ErrorCode.INTERNAL,
+          "Error verifying App Check token with backend: " + e.getMessage(),
+          e,
+          null,
+          AppCheckErrorCode.SERVICE_ERROR);
     } finally {
       ApiClientUtils.disconnectQuietly(httpResponse);
     }

src/test/java/com/google/firebase/appcheck/AppCheckErrorCodeTest.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.firebase.appcheck;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+
+import org.junit.Test;
+
+public class AppCheckErrorCodeTest {
+
+  @Test
+  public void testEnum() {
+    assertNotNull(AppCheckErrorCode.valueOf("INVALID_ARGUMENT"));
+    assertNotNull(AppCheckErrorCode.valueOf("INVALID_APP_CHECK_TOKEN"));
+    assertNotNull(AppCheckErrorCode.valueOf("APP_CHECK_TOKEN_EXPIRED"));
+    assertNotNull(AppCheckErrorCode.valueOf("INTERNAL_ERROR"));
+    assertNotNull(AppCheckErrorCode.valueOf("SERVICE_ERROR"));
+    assertEquals(5, AppCheckErrorCode.values().length);
+  }
+}

src/test/java/com/google/firebase/appcheck/FirebaseAppCheckExceptionTest.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.firebase.appcheck;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+
+import com.google.firebase.ErrorCode;
+import com.google.firebase.FirebaseException;
+import org.junit.Test;
+
+public class FirebaseAppCheckExceptionTest {
+
+  @Test
+  public void testConstructorWithAppCheckErrorCode() {
+    Exception cause = new Exception("cause");
+    FirebaseAppCheckException exception =
+        new FirebaseAppCheckException(
+            ErrorCode.INVALID_ARGUMENT,
+            "Invalid token",
+            cause,
+            null,
+            AppCheckErrorCode.APP_CHECK_TOKEN_EXPIRED);
+
+    assertEquals(ErrorCode.INVALID_ARGUMENT, exception.getErrorCode());
+    assertEquals("Invalid token", exception.getMessage());
+    assertSame(cause, exception.getCause());
+    assertNull(exception.getHttpResponse());
+    assertEquals(AppCheckErrorCode.APP_CHECK_TOKEN_EXPIRED, exception.getAppCheckErrorCode());
+  }
+
+  @Test
+  public void testConstructorWithoutAppCheckErrorCode() {
+    FirebaseAppCheckException exception =
+        new FirebaseAppCheckException(ErrorCode.INTERNAL, "Internal error");
+
+    assertEquals(ErrorCode.INTERNAL, exception.getErrorCode());
+    assertEquals("Internal error", exception.getMessage());
+    assertNull(exception.getCause());
+    assertNull(exception.getHttpResponse());
+    assertNull(exception.getAppCheckErrorCode());
+  }
+
+  @Test
+  public void testConstructorWithCause() {
+    Exception cause = new Exception("cause");
+    FirebaseAppCheckException exception =
+        new FirebaseAppCheckException(ErrorCode.UNKNOWN, "Unknown error", cause);
+
+    assertEquals(ErrorCode.UNKNOWN, exception.getErrorCode());
+    assertEquals("Unknown error", exception.getMessage());
+    assertSame(cause, exception.getCause());
+    assertNull(exception.getAppCheckErrorCode());
+  }
+
+  @Test
+  public void testConstructorFromFirebaseException() {
+    FirebaseException base =
+        new FirebaseException(ErrorCode.UNAVAILABLE, "Service unavailable", null);
+    FirebaseAppCheckException exception = new FirebaseAppCheckException(base);
+
+    assertEquals(ErrorCode.UNAVAILABLE, exception.getErrorCode());
+    assertEquals("Service unavailable", exception.getMessage());
+    assertNull(exception.getAppCheckErrorCode());
+  }
+}

src/test/java/com/google/firebase/appcheck/internal/AppCheckTokenVerifierTest.java

@@ -44,6 +44,7 @@
 import com.google.firebase.FirebaseApp;
 import com.google.firebase.FirebaseOptions;
 import com.google.firebase.TestOnlyImplFirebaseTrampolines;
+import com.google.firebase.appcheck.AppCheckErrorCode;
 import com.google.firebase.appcheck.DecodedAppCheckToken;
 import com.google.firebase.appcheck.FirebaseAppCheckException;
 import com.google.firebase.appcheck.VerifyAppCheckTokenOptions;
@@ -506,6 +507,7 @@ protected JWKSource<SecurityContext> createKeySource() {
     FirebaseAppCheckException ex =
         assertThrows(FirebaseAppCheckException.class, () -> realVerifier.verifyToken(token));
     assertEquals(ErrorCode.INVALID_ARGUMENT, ex.getErrorCode());
+    assertEquals(AppCheckErrorCode.INVALID_APP_CHECK_TOKEN, ex.getAppCheckErrorCode());
     assertTrue(ex.getMessage().contains("Failed to verify App Check token signature"));
   }
 
@@ -546,6 +548,7 @@ protected JWKSource<SecurityContext> createKeySource() {
     FirebaseAppCheckException ex =
         assertThrows(FirebaseAppCheckException.class, () -> realVerifier.verifyToken(token));
     assertEquals(ErrorCode.INVALID_ARGUMENT, ex.getErrorCode());
+    assertEquals(AppCheckErrorCode.APP_CHECK_TOKEN_EXPIRED, ex.getAppCheckErrorCode());
     assertTrue(ex.getMessage().contains("Firebase App Check token has expired."));
   }
 }