Update exception messages

server/src/main/java/org/elasticsearch/cluster/NotMasterException.java

@@ -9,12 +9,20 @@
 package org.elasticsearch.cluster;
 
 import org.elasticsearch.ElasticsearchException;
+import org.elasticsearch.action.support.master.TransportMasterNodeAction;
+import org.elasticsearch.cluster.coordination.FailedToCommitClusterStateException;
 import org.elasticsearch.common.io.stream.StreamInput;
 
 import java.io.IOException;
 
 /**
- * Exception which indicates that an operation failed because the node stopped being the elected master.
+ * Exception indicating that a cluster state update operation failed because the node stopped being the elected master.
+ * Since this exception is thrown prior to the cluster state publication, it should only be used when the cluster state update
+ * <i>definitely</i> did not happen, and there is no possibility the next master committed the cluster state update.
+ *
+ * This is different from {@link FailedToCommitClusterStateException}.
+ *
+ * This exception is retryable within {@link TransportMasterNodeAction}.
  */
 public class NotMasterException extends ElasticsearchException {
 

server/src/main/java/org/elasticsearch/cluster/coordination/FailedToCommitClusterStateException.java

@@ -9,14 +9,20 @@
 package org.elasticsearch.cluster.coordination;
 
 import org.elasticsearch.ElasticsearchException;
+import org.elasticsearch.action.support.master.TransportMasterNodeAction;
+import org.elasticsearch.cluster.NotMasterException;
 import org.elasticsearch.common.io.stream.StreamInput;
 
 import java.io.IOException;
 
 /**
  * Thrown when a cluster state publication fails to commit the new cluster state. If publication fails then a new master is elected but the
- * update might or might not take effect, depending on whether or not the newly-elected master accepted the published state that failed to
- * be committed.
+ * update might or might not take effect, depending on whether the newly-elected master accepted the published state that failed to
+ * be committed. This exception should only be used when there is <i>ambiguity</i> whether a state update took effect or not.
+ *
+ * This is different from {@link NotMasterException} where we know for certain that a state update never took effect.
+ *
+ * This exception is retryable within {@link TransportMasterNodeAction}.
  *
  * See {@link ClusterStatePublisher} for more details.
  */