Add RemoteTransportException for remote transport/server faults

driver/src/main/java/oracle/nosql/driver/RemoteTransportException.java

@@ -0,0 +1,36 @@
+/*-
+ * Copyright (c) 2011, 2025 Oracle and/or its affiliates. All rights reserved.
+ *
+ * Licensed under the Universal Permissive License v 1.0 as shown at
+ *  https://oss.oracle.com/licenses/upl/
+ */
+
+package oracle.nosql.driver;
+
+/**
+ * Thrown when the service reports a server-side {@code FaultException} that
+ * appears to have originated from a remote networking/transport failure
+ * between service components.
+ * <p>
+ * This exception is intentionally <em>not</em> retried by the Java SDK's
+ * internal retry handler. Application code may choose to retry, using the
+ * following guidance:
+ * <ul>
+ *   <li><b>Idempotent operations</b>: it is generally safe to retry.</li>
+ *   <li><b>Non-idempotent operations</b>: first perform a read to determine
+ *       whether the operation may have already succeeded, and then retry
+ *       only if necessary.</li>
+ * </ul>
+ */
+public class RemoteTransportException extends NoSQLException {
+
+    private static final long serialVersionUID = 1L;
+
+    public RemoteTransportException(String msg) {
+        super(msg);
+    }
+
+    public RemoteTransportException(String msg, Throwable cause) {
+        super(msg, cause);
+    }
+}

driver/src/main/java/oracle/nosql/driver/ops/serde/BinaryProtocol.java

@@ -18,6 +18,7 @@
 import oracle.nosql.driver.Durability;
 import oracle.nosql.driver.EvolutionLimitException;
 import oracle.nosql.driver.FieldRange;
+import oracle.nosql.driver.RemoteTransportException;
 import oracle.nosql.driver.IndexExistsException;
 import oracle.nosql.driver.IndexLimitException;
 import oracle.nosql.driver.IndexNotFoundException;
@@ -437,6 +438,8 @@ public static RuntimeException mapException(int code, String msg) {
             return new IllegalArgumentException(msg);
         case RECOMPILE_QUERY:
             return new PrepareQueryException(msg);
+        case REMOTE_ERROR:
+            return new RemoteTransportException(msg);
         default:
             return new NoSQLException("Unknown error code " + code + ": " +
                                       msg);

driver/src/main/java/oracle/nosql/driver/util/BinaryProtocol.java

@@ -222,6 +222,14 @@ public static boolean isTenantOperation(OpCode op) {
     public static final int UNKNOWN_ERROR = 125;
     public static final int ILLEGAL_STATE = 126;
 
+    /*
+     * A server-side FaultException that appears to have originated from a
+     * remote networking/transport failure. This is intentionally in the
+     * NON-retryable (125+) range so that the Java SDK does not perform
+     * automatic retries; callers can decide whether/how to retry.
+     */
+    public static final int REMOTE_ERROR = 127;
+
     /*
      * Return true if the errorCode means a user-generated error.
      */