From ee64093423957eff2b9f544b28ea80d550e47106 Mon Sep 17 00:00:00 2001
From: Ian Botsford <83236726+ianbotsf@users.noreply.github.com>
Date: Tue, 9 Sep 2025 17:07:56 +0000
Subject: [PATCH] docs: improve documentation for `AwsRetryPolicy`

---
 .../13ef4936-91c8-45ec-9cb3-98f651488130.json |  5 +++
 .../runtime/http/retries/AwsRetryPolicy.kt    | 34 ++++++++++++++++++-
 2 files changed, 38 insertions(+), 1 deletion(-)
 create mode 100644 .changes/13ef4936-91c8-45ec-9cb3-98f651488130.json

diff --git a/.changes/13ef4936-91c8-45ec-9cb3-98f651488130.json b/.changes/13ef4936-91c8-45ec-9cb3-98f651488130.json
new file mode 100644
index 00000000000..3cdbaa63635
--- /dev/null
+++ b/.changes/13ef4936-91c8-45ec-9cb3-98f651488130.json
@@ -0,0 +1,5 @@
+{
+    "id": "13ef4936-91c8-45ec-9cb3-98f651488130",
+    "type": "documentation",
+    "description": "Improve documentation for [`AwsRetryPolicy`](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/aws-http/aws.sdk.kotlin.runtime.http.retries/-aws-retry-policy/)"
+}
\ No newline at end of file
diff --git a/aws-runtime/aws-http/common/src/aws/sdk/kotlin/runtime/http/retries/AwsRetryPolicy.kt b/aws-runtime/aws-http/common/src/aws/sdk/kotlin/runtime/http/retries/AwsRetryPolicy.kt
index 807cb9018aa..c8ab3182dfe 100644
--- a/aws-runtime/aws-http/common/src/aws/sdk/kotlin/runtime/http/retries/AwsRetryPolicy.kt
+++ b/aws-runtime/aws-http/common/src/aws/sdk/kotlin/runtime/http/retries/AwsRetryPolicy.kt
@@ -9,9 +9,41 @@ import aws.smithy.kotlin.runtime.ServiceErrorMetadata
 import aws.smithy.kotlin.runtime.ServiceException
 import aws.smithy.kotlin.runtime.http.response.HttpResponse
 import aws.smithy.kotlin.runtime.retries.policy.RetryDirective
-import aws.smithy.kotlin.runtime.retries.policy.RetryErrorType.*
+import aws.smithy.kotlin.runtime.retries.policy.RetryErrorType.Throttling
+import aws.smithy.kotlin.runtime.retries.policy.RetryErrorType.Transient
 import aws.smithy.kotlin.runtime.retries.policy.StandardRetryPolicy
 
+/**
+ * The standard policy for AWS service clients that defines which error conditions are retryable and how. This policy
+ * will evaluate the following exceptions as retryable:
+ *
+ * * Any [ServiceException] with an `sdkErrorMetadata.errorCode` of:
+ *   * `BandwidthLimitExceeded`
+ *   * `EC2ThrottledException`
+ *   * `IDPCommunicationError`
+ *   * `LimitExceededException`
+ *   * `PriorRequestNotComplete`
+ *   * `ProvisionedThroughputExceededException`
+ *   * `RequestLimitExceeded`
+ *   * `RequestThrottled`
+ *   * `RequestThrottledException`
+ *   * `RequestTimeout`
+ *   * `RequestTimeoutException`
+ *   * `SlowDown`
+ *   * `ThrottledException`
+ *   * `Throttling`
+ *   * `ThrottlingException`
+ *   * `TooManyRequestsException`
+ *   * `TransactionInProgressException`
+ * * Any [ServiceException] with an `sdkErrorMetadata.statusCode` of:
+ *   * 500 (Internal Service Error)
+ *   * 502 (Bad Gateway)
+ *   * 503 (Service Unavailable)
+ *   * 504 (Gateway Timeout)
+ *
+ * If none of those conditions match, this policy delegates to [StandardRetryPolicy]. See that class's documentation for
+ * more information about how it evaluates exceptions.
+ */
 public open class AwsRetryPolicy : StandardRetryPolicy() {
     public companion object {
         /**