Update exception messages

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

@@ -14,7 +14,13 @@
 import java.io.IOException;
 
 /**
- * Exception which indicates that an operation failed because the node stopped being the elected master.
+ * Exception indicating that an 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
+ * *definitely* did not happen, and there is no possibility the next master committed the cluster state update.
+ *
+ * This is different to the {@code FailedToCommitClusterStateException}
+ *
+ * This exception is retryable within {@code TransportNodeMasterAction}.
  */
 public class NotMasterException extends ElasticsearchException {
 

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

@@ -15,8 +15,10 @@
 
 /**
  * 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 *ambiguity* whether a state update took effect or not.
+ *
+ * This exception is retryable within {@code TransportNodeMasterAction}.
  *
  * See {@link ClusterStatePublisher} for more details.
  */