Clarification on which SdkClientException subclasses may be retryable (#3016)

Author: cenedhryn

core/sdk-core/src/main/java/software/amazon/awssdk/core/exception/SdkClientException.java

@@ -16,15 +16,19 @@
 package software.amazon.awssdk.core.exception;
 
 import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.core.internal.retry.SdkDefaultRetrySetting;
 
 /**
  * Base type for all client exceptions thrown by the SDK.
  *
  * This exception is thrown when service could not be contacted for a response,
  * or when client is unable to parse the response from service.
- *
- * All exceptions that extend {@link SdkClientException} are assumed to be
- * not retryable.
+ * <p>
+ * Exceptions that extend {@link SdkClientException} are assumed to be not retryable, with a few exceptions:
+ * <ul>
+ *     <li>{@link RetryableException} - usable when calls should explicitly be retried</li>
+ *     <li>Exceptions mentioned as a retryable exception in {@link SdkDefaultRetrySetting}</li>
+ * </ul>
  *
  * @see SdkServiceException
  */