本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

重試行為

當請求因暫時性錯誤或限流而 AWS 服務 失敗時，軟體開發套件可以自動重試請求。此頁面說明如何設定重試，以及如何在內部運作。

設定重試

您可以控制開發套件使用的重試策略，以及重試次數。

選擇重試模式

重試模式會決定 SDK 在請求失敗時的行為。有三種模式可用：標準、適應性和傳統。

標準模式 （預設）

標準模式會使用指數退避搭配抖動重試失敗的請求。它會針對暫時性錯誤 （例如網路逾時） 使用較短的延遲，並針對限流錯誤 （例如 ) 使用較長的延遲ThrottlingException。

標準模式包含重試配額，也就是權杖儲存貯體，可為每個重試扣除權杖，並在請求成功時補充權杖。當可用的字符用盡時，開發套件會傳回錯誤而不重試，因此您的應用程式會快速失敗，而不是等待不太可能成功的重試。這也有助於減少重試流量，以更快的速度解決服務中斷。在正常操作期間，配額會保持完整且沒有作用。重試配額永遠不會延遲或封鎖初始請求。只有重試會受到影響。如需詳細資訊，請參閱重試配額 （權杖儲存貯體）。

除非您有特定理由選擇其他模式，否則請使用標準模式。

自適應模式

自適應模式包含標準模式中的所有項目，以及用戶端速率限制器。速率限制器會追蹤調節回應，並調整 SDK 傳送請求的速率。與標準模式不同，自適應模式可能會在偵測到限流時延遲或封鎖初始請求，而不只是重試。

速率限制器會依 SDK 用戶端執行個體運作。來自用戶端的所有請求都會共用相同的速率限制，無論其以哪個 API 操作或資源為目標。

何時使用自適應模式：

不使用自適應模式時：

不建議將自適應模式作為一般預設值。

傳統模式

傳統模式是引進標準模式之前，每個 SDK 使用的重試行為。它不包含標準化的重試配額。某些 SDKs（例如 Java) 在舊版模式中有自己的重試配額實作，但軟體SDKs的行為不一致。如果沒有標準化配額，用戶端會在服務中斷期間繼續以完整速率重試。這會在不太可能成功的請求上連結執行緒和連線，同時新增可能會延遲服務復原的負載。

傳統模式會因 SDKs而異。重試計數、退避計時、可重試錯誤集和限流行為因語言而異。在 SDKs程式碼可能會有不同的行為。

提供：Java、Python、Ruby、PHP、C++、CLI

不適用於：.NET、Go、Kotlin、Rust、Swift、JavaScript

傳統模式為了回溯相容性而存在。如果您目前使用舊版模式，請切換到標準模式。

重試設定

下列設定控制重試行為。您可以透過環境變數、共用組態檔案 (~/.aws/config) 或程式碼中的用戶端組態來設定它們。

的最大嘗試次數值3表示 SDK 會提出一個初始請求，最多重試兩次。設定嘗試完全1停用重試次數上限。

組態優先順序

當您在多個位置指定相同的設定時，軟體開發套件會使用下列優先順序來解析值，從最高到最低：

這遵循標準 AWS SDK 組態優先順序。在較高層級設定的值一律會覆寫在較低層級設定的值。例如，如果您在 retry_mode=standard中將 AWS_RETRY_MODE=adaptive設定為環境變數 和 ~/.aws/config，則 SDK 會使用自適應模式。

語言特定組態

此頁面 (retry_mode 和 max_attempts) 所述的跨 SDK 設定適用於所有 SDKs。不過，在程式碼中設定重試的 API 會因語言而異。如需特定語言組態選項，例如自訂退避策略、其他可重試的錯誤，以及重試配額調校，請參閱開發套件的開發人員指南。

重試的運作方式

本節說明 AWS SDKs如何處理失敗的請求：哪些錯誤觸發重試、SDK 在嘗試之間等待多久，以及何時停止重試。

請求失敗時會發生什麼情況

當您透過 AWS SDK 進行 API 呼叫時，軟體開發套件會遵循以下順序：

SDK 會重複此迴圈，直到請求成功、達到嘗試次數上限、耗盡重試配額，或發生無法重試的錯誤為止。整個程序都是自動的。您的應用程式會看到成功回應或最終錯誤。

重試哪些錯誤

開發套件會將每個失敗的請求分類為三個類別之一：暫時性、限流或無法重試。此分類會決定 SDK 是否重試請求，以及重試之前的等待時間。

分類是根據服務回應中的錯誤碼和 HTTP 狀態碼。例如，具有錯誤碼的 HTTP 400 RequestTimeout 會分類為暫時性並重試。具有 的 HTTP 400 ValidationException 被歸類為不可重試並立即傳回。

錯誤分類

暫時性錯誤會以短暫的基礎延遲 (50 毫秒） 重試：

調節錯誤會以較長的基本延遲 (1，000 毫秒） 重試：

無法重試的錯誤 （例如 AccessDeniedException、ValidationException、ResourceNotFoundException) 會立即傳回至您的程式碼。

調節錯誤表示服務因為速率限制而主動拒絕您的請求，因此 SDK 在重試之前會等待更長的時間，讓服務有時間復原容量。如需特定延遲，軟體開發套件等待多久請參閱 。

軟體開發套件等待多久

SDK 使用指數退避搭配完全抖動。平均而言，每次重試會等待比上次更久的時間，並隨機分散來自多個用戶端的請求。

依錯誤類型區分的基本延遲

基本延遲取決於錯誤是暫時性還是限流：

退避公式

SDK 使用此公式計算每個重試延遲：

delay = random(0, 1) × min(20,000 ms, base_delay × 2^retry)

其中：

退避上限為 20 秒。無論已嘗試多少次，個別延遲都不會超過 20 秒。

工作範例

範例 1：暫時性錯誤，最多嘗試 3 次

在兩次重試中新增的總延遲平均約為 75 毫秒。

範例 2：調節錯誤，最多嘗試 3 次

在兩次重試中新增的總延遲平均約為 1，500 毫秒。

範例 3：暫時性錯誤，達到退避上限

基本延遲為 50 毫秒時，上限之前的計算延遲為：

對於暫時性錯誤，上限會在第 10 次重試 （第 11 次嘗試） 時生效。對於基礎為 1，000 毫秒的限流錯誤，上限會在第 6 次重試時生效。

抖動為何重要

隨機乘數稱為完整抖動。如果沒有它，同時遇到錯誤的所有用戶端都會同時重試，造成大量的重試流量 (「雷擊雜湊」問題）。完全抖動會將重試均勻分散到整個退避時段，讓服務收到穩定的請求，而不是同步峰值。

例如，假設 1，000 個用戶端都同時收到 503。完整抖動會在 50 毫秒的時段均勻分配其第一次重試，而不是完全在 50 毫秒進行全部 1，000 次重試。

伺服器導向重試計時

有些 會在錯誤回應中 AWS 服務 包含 x-amz-retry-after標頭。標頭值是以毫秒為單位的延遲。出現此標頭時，開發套件會使用伺服器指定的延遲，並固定為計算的退避延遲的最小值，以及計算的退避延遲的最大值加上 5，000 毫秒。由於計算的退避本身限制為 20 秒，因此有效的伺服器導向延遲上限為 25 秒。SDK 不會套用抖動到此值，因為預期服務會抖動。這可讓服務在預期有可用容量時準確通訊。

重試配額 （權杖儲存貯體）

開發套件會維護內部字符預算，以追蹤成功請求與失敗的比例。當失敗普遍發生時，預算會耗盡，開發套件會直接傳回錯誤。您的應用程式會快速失敗，而不是等待不太可能成功的重試。這也會減少重試流量，協助服務中斷更快地解決。

重試配額的運作方式

字符預算開始已滿。每次重試嘗試都會扣除權杖。當重試成功時，軟體開發套件會還原該重試所耗用的字符。當請求在第一次嘗試時成功 （不需要重試），軟體開發套件會還原 1 個字符。當預算達到零時，開發套件會停止重試，並將錯誤直接傳回至您的程式碼。

暫時性重試的成本越高，就會反映其不同的失敗模式。500 和連線失敗等暫時性錯誤通常表示整個服務的問題。在這些情況下，持續重試不太可能成功。它會為您的呼叫增加延遲、將用戶端資源綁定起來，並可能延遲每個人的復原。調節錯誤表示服務需要更多時間才能成功請求。軟體開發套件會在重試之間等待更長的時間，以改善成功的可能性。

配額區塊何時重試

重試配額會隨時追蹤權杖，但只會在預算用盡時封鎖重試。在正常操作期間，幾乎所有請求都會成功，且預算會保持滿載。配額對重試沒有可觀測的影響。

成功重試只會還原自己的字符成本 (14 或 5 個字符），而不是相同請求中先前失敗重試的成本。例如，如果第一次重試失敗且第二次成功，預算會遺失 14 個權杖。當重試耗盡所有嘗試但未成功時，預算會消耗最快，但當請求在成功之前需要多次重試時也會逐漸耗盡。

在預設嘗試次數上限 3 次的情況下，當超過大約 22% 的請求導致持續暫時性失敗，或限流錯誤超過大約 32% 時，配額會開始耗盡。低於這些速率時，成功的請求會比失敗的重試耗盡預算更快地補充預算。

預算的 500 個權杖開始平衡提供緩衝，可吸收短暫的故障暴增。錯誤短暫激增，即使嚴重，也不會封鎖重試，除非它持續夠長的時間來耗盡緩衝區。

實際影響

服務特定的行為

DynamoDB

DynamoDB 用戶端使用針對 DynamoDB 低延遲設定檔最佳化的調校預設值：

這些預設值同時適用於 Amazon DynamoDB 和 DynamoDB Streams。

長輪詢操作

某些 AWS 操作使用長輪詢。他們可以保持連線開啟，等待工作到達。這些操作會受到特殊的重試處理：

特殊行為：當重試配額耗盡且重試遭到封鎖時 ( 中的步驟 7請求失敗時會發生什麼情況)，軟體開發套件仍會套用退避延遲，再將錯誤傳回至程式碼。

這很重要，因為長輪詢操作通常在緊密迴圈中呼叫。您的程式碼會呼叫 ReceiveMessage、處理任何訊息，然後立即ReceiveMessage再次呼叫 。如果沒有強制退避，耗盡的字符預算會導致 SDK 在不延遲的情況下傳回錯誤。然後，您的輪詢迴圈會立即傳送下一個請求、激增用戶端 CPU 用量並產生額外的流量。強制退避延遲會中斷此週期，讓用戶端資源用量和輪詢速率在失敗期間保持可管理。

支援 AWS SDKs和工具

下表列出每個 SDK 中更新的重試行為的可用性。如需開發套件特定的詳細資訊，包括最低版本、before-and-after預設值和程式碼範例，請參閱 GitHub 追蹤問題。