address comments

Author: Stephen Wu

hadoop-tools/hadoop-aws/src/main/java/org/apache/hadoop/fs/s3a/Constants.java

@@ -1204,8 +1204,17 @@ private Constants() {
    */
   public static final int DEFAULT_AWS_S3_VECTOR_READS_MAX_MERGED_READ_SIZE = 1253376; //1M
 
-  public static final String FAIL_ON_AWS_BAD_REQUEST = "fs.s3a.retry.failOnAwsBadRequest";
+  /**
+   * Flag for immediate failure when observing a {@link AWSBadRequestException}.
+   * If it's disabled and set to false, the failure is treated as retryable.
+   * Value {@value}.
+   */
+  public static final String FAIL_ON_AWS_BAD_REQUEST = "fs.s3a.fail.on.aws.bad.request";
 
+  /**
+   * Default value for immediate failure when observing a
+   * {@link AWSBadRequestException}: {@value}.
+   */
   public static final boolean DEFAULT_FAIL_ON_AWS_BAD_REQUEST = true;
 
 }

hadoop-tools/hadoop-aws/src/site/markdown/tools/hadoop-aws/index.md

@@ -1118,12 +1118,15 @@ from them.
 
 * Connection timeout: `ConnectTimeoutException`. Timeout before
 setting up a connection to the S3 endpoint (or proxy).
-* HTTP response status code 400, "Bad Request"
+* HTTP response status code 400, "Bad Request" aka `AWSBadRequestException`
 
 The status code 400, Bad Request usually means that the request
 is unrecoverable; it's the generic "No" response. Very rarely it
 does recover, which is why it is in this category, rather than that
-of unrecoverable failures.
+of unrecoverable failures. The default behavior fails immediately
+without retry. If your system is failure sensitive, you can
+configure `fs.s3a.fail.on.aws.bad.request` to `false` and allow 
+to retry when observing a Bad Request with status code 400. 
 
 These failures will be retried with an exponential sleep interval set in
 `fs.s3a.retry.interval`, up to the limit set in `fs.s3a.retry.limit`.