DynamoDB ProvisionedThroughputExceededException

TL;DR — 你的讀寫速度超過了資料表或索引所能承載的範圍。把資料表切換到隨需容量、調高佈建的 RCU/WCU（或啟用自動調整規模）、保留 SDK 預設的指數退避重試，並分散流量，讓單一分割區索引鍵不至於過熱。

這是什麼意思

ProvisionedThroughputExceededException: You exceeded your maximum allowed
provisioned throughput for a table or for one or more global secondary indexes.

在佈建容量的資料表上，你超過了讀取／寫入容量單位 — 可能是整體超過，或（更常見）是在單一分割區上超過。它是 HTTP 400，但與 ValidationException 不同，它可以重試：AWS SDK 會以指數退避自動重試，所以偶爾出現是正常的。持續出現則代表真的容量不足或有熱鍵。這個錯誤帶有 ThrottlingReason 欄位（例如 TableReadProvisionedThroughputExceeded）以及受影響資源的 ARN，讓你能辨別是哪張資料表或索引被節流、以及在哪種操作類型上。

為什麼會發生

相對於實際流量，佈建容量不足。
熱分割區 — 流量集中在單一分割區索引鍵上，因此某個分割區分到的那份容量被耗盡，而整張資料表看起來卻使用率偏低。
突發流量的變化快過自動調整規模的反應 — 它是依據已消耗容量的指標來調整容量，所以突然的階梯式變化會在擴容到位之前就先被節流。
大型 scan 或大量匯入一次吃光所有容量。
某個 GSI 的容量低於寫入速率 — 被節流的 GSI 會連帶節流基礎資料表。

如何修正

如果流量難以預測，就切換到隨需容量 — 它會自動擴縮，這個錯誤基本上就消失了（改成按請求付費）。
若你要留在佈建模式，就調高佈建的 RCU/WCU，或以合理的目標使用率啟用自動調整規模。
保留指數退避重試 — SDK 預設就會這麼做；別關掉它。突發型工作負載請使用 adaptive 重試模式。
修正熱分割區 — 提高鍵的基數／對熱鍵做寫入分片，讓負載分散到各分割區。
限制大量作業的速率，並快取熱門讀取（DAX 或應用程式快取）以卸除讀取壓力。

常見問題

我要怎麼修正 ProvisionedThroughputExceededException？ 你的讀寫速度超過了資料表或索引所能承載的範圍。把資料表切換到隨需容量、調高佈建的 RCU/WCU（或啟用自動調整規模）、保留 SDK 預設的指數退避重試，並分散流量，讓單一分割區索引鍵不至於過熱。

重現方式

以 1 RCU 佈建一張資料表，放入一個略小於 4 KB 的項目，然後在緊密迴圈中以強一致方式讀回它：

import boto3
ddb = boto3.client('dynamodb', region_name='us-east-1')
# table created with ProvisionedThroughput={'ReadCapacityUnits': 1, 'WriteCapacityUnits': 1}
ddb.put_item(TableName='my-table', Item={'pk': {'S': 'A'}, 'blob': {'S': 'x' * 3500}})
while True:
    ddb.get_item(TableName='my-table', Key={'pk': {'S': 'A'}}, ConsistentRead=True)

實際輸出：

ProvisionedThroughputExceededException: The level of configured provisioned throughput for the table was exceeded. Consider increasing your provisioning level with the UpdateTable API.
HTTP 400

在一張全新建立、且關閉 SDK 重試的資料表上，觸發它花了 49 次讀取。 那個數字才是有趣的地方：1 RCU 的資料表不會在第二次請求就失敗，因為 DynamoDB 會先把累積的爆量容量借給你 — 所以太早停止的負載測試，會把一張其實不健康的資料表回報成健康。這個假象的另一半來自 SDK，它預設會替你重試被節流的請求；請像上面那樣關閉重試，否則這個錯誤會一直隱形，直到它變成延遲問題為止。

參考資料

最後於 2026-07-13 對照上方連結的官方 AWS 文件驗證。

已於 2026-07-26 透過 boto3 1.43.56，在一張以 1 RCU 佈建、且關閉 SDK 重試的資料表上，對照 us-east-1 的線上 DynamoDB 服務重現 — 上方輸出為逐字原文。