Add KnnCircuitBreakerException and modify exception message

CHANGELOG.md

@@ -15,6 +15,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ## [Unreleased 2.x](https://github.com/opensearch-project/k-NN/compare/2.14...2.x)
 ### Features
 ### Enhancements
+* Add KnnCircuitBreakerException and modify exception message [#1688](https://github.com/opensearch-project/k-NN/pull/1688)
 ### Bug Fixes
 ### Infrastructure
 ### Documentation

src/main/java/org/opensearch/knn/index/KnnCircuitBreakerException.java

@@ -0,0 +1,65 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ *
+ * Modifications Copyright OpenSearch Contributors. See
+ * GitHub history for details.
+ */
+
+package org.opensearch.knn.index;
+
+/**
+ * An exception to be thrown when the k-NN circuit breaker is triggered.
+ */
+public class KnnCircuitBreakerException extends RuntimeException {
+
+    /**
+     * Constructs a KnnCircuitBreakerException with the specified detail
+     * message.  A detail message is a String that describes this particular
+     * exception.
+     *
+     * @param message the String that contains a detailed message
+     */
+    public KnnCircuitBreakerException(final String message) {
+        super(message);
+    }
+
+    /**
+     * Constructs a new exception with the specified detail message and
+     * cause.
+     *
+     * <p>Note that the detail message associated with {@code cause} is
+     * <i>not</i> automatically incorporated in this exception's detail
+     * message.
+     *
+     * @param  message the detail message (which is saved for later retrieval
+     *         by the {@link Throwable#getMessage()} method).
+     * @param  cause the cause (which is saved for later retrieval by the
+     *         {@link Throwable#getCause()} method).  (A {@code null} value
+     *         is permitted, and indicates that the cause is nonexistent or
+     *         unknown.)
+     */
+    public KnnCircuitBreakerException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /**
+     * Constructs a new exception with the specified cause and a detail
+     * message of {@code (cause==null ? null : cause.toString())} (which
+     * typically contains the class and detail message of {@code cause}).
+     * This constructor is useful for exceptions that are little more than
+     * wrappers for other throwables (for example, {@link
+     * java.security.PrivilegedActionException}).
+     *
+     * @param  cause the cause (which is saved for later retrieval by the
+     *         {@link Throwable#getCause()} method).  (A {@code null} value is
+     *         permitted, and indicates that the cause is nonexistent or
+     *         unknown.)
+     */
+    public KnnCircuitBreakerException(Throwable cause) {
+        super(cause);
+    }
+}

src/main/java/org/opensearch/knn/index/mapper/KNNVectorFieldMapper.java

@@ -42,6 +42,7 @@
 import org.opensearch.index.query.QueryShardContext;
 import org.opensearch.index.query.QueryShardException;
 import org.opensearch.knn.common.KNNConstants;
+import org.opensearch.knn.index.KnnCircuitBreakerException;
 import org.opensearch.knn.index.KNNMethodContext;
 import org.opensearch.knn.index.KNNSettings;
 import org.opensearch.knn.index.KNNVectorIndexFieldData;
@@ -624,8 +625,8 @@ protected boolean isFaissSQClipToFP16RangeEnabled(MethodComponentContext methodC
 
     void validateIfCircuitBreakerIsNotTriggered() {
         if (KNNSettings.isCircuitBreakerTriggered()) {
-            throw new IllegalStateException(
-                "Indexing knn vector fields is rejected as circuit breaker triggered. Check _opendistro/_knn/stats for detailed state"
+            throw new KnnCircuitBreakerException(
+                "Parsing the created knn vector fields prior to indexing has failed as the circuit breaker triggered.  This indicates that the cluster is low on memory resources and cannot index more documents at the moment. Check _plugins/_knn/stats for the circuit breaker status."
             );
         }
     }

src/test/java/org/opensearch/knn/index/OpenSearchIT.java

@@ -189,8 +189,8 @@ public void testAddDoc_blockedWhenCbTrips() throws Exception {
 
         Float[] vector = { 6.0f, 6.0f };
         ResponseException ex = expectThrows(ResponseException.class, () -> addKnnDoc(INDEX_NAME, "1", FIELD_NAME, vector));
-        String expMessage = "Indexing knn vector fields is rejected as circuit breaker triggered."
-            + " Check _opendistro/_knn/stats for detailed state";
+        String expMessage =
+            "Parsing the created knn vector fields prior to indexing has failed as the circuit breaker triggered.  This indicates that the cluster is low on memory resources and cannot index more documents at the moment. Check _plugins/_knn/stats for the circuit breaker status.";
         assertThat(EntityUtils.toString(ex.getResponse().getEntity()), containsString(expMessage));
 
         // reset
@@ -207,8 +207,8 @@ public void testUpdateDoc_blockedWhenCbTrips() throws Exception {
         updateClusterSettings("knn.circuit_breaker.triggered", "true");
         Float[] updatedVector = { 8.0f, 8.0f };
         ResponseException ex = expectThrows(ResponseException.class, () -> updateKnnDoc(INDEX_NAME, "1", FIELD_NAME, vector));
-        String expMessage = "Indexing knn vector fields is rejected as circuit breaker triggered."
-            + " Check _opendistro/_knn/stats for detailed state";
+        String expMessage =
+            "Parsing the created knn vector fields prior to indexing has failed as the circuit breaker triggered.  This indicates that the cluster is low on memory resources and cannot index more documents at the moment. Check _plugins/_knn/stats for the circuit breaker status.";
         assertThat(EntityUtils.toString(ex.getResponse().getEntity()), containsString(expMessage));
 
         // reset