DynamoDB ProvisionedThroughputExceededException

TL;DR — テーブルやインデックスが提供できるより速く読み書きしています。テーブルをオンデマンドキャパシティに切り替え、プロビジョニング済みの RCU/WCU を引き上げる（または Auto Scaling を有効にする）、SDK 既定の指数バックオフ付きリトライを維持する、そして1つのパーティションキーがホットにならないようトラフィックを分散させてください。

意味

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 を伴うので、どのテーブルやインデックスが、どの操作種別でスロットリングされたかが分かります。

発生する理由

• 実際のトラフィックに対する キャパシティのプロビジョニング不足。
• ホットパーティション — トラフィックが1つのパーティションキーに集中し、テーブル全体では余裕があるように見えるのに、単一パーティションの取り分が使い切られている。
• Auto Scaling が反応できないほど急峻なトラフィック — Auto Scaling は消費キャパシティのメトリクスに応じて調整するため、急な段差ではスケールアップが効く前にスロットリングされます。
• 大きな Scan や一括インポート が、一度にすべてのキャパシティを消費している。
• 書き込みレートよりキャパシティが低い GSI — スロットリングされた GSI はベーステーブルもスロットリングします。

修正方法

1. トラフィックが読めないなら オンデマンドキャパシティに切り替えます — 自動でスケールし、このエラーは事実上なくなります（代わりにリクエスト単位で課金されます）。
2. プロビジョニング済みのまま行くなら、RCU/WCU を引き上げる か、妥当な目標使用率で Auto Scaling を有効にします。
3. 指数バックオフ付きのリトライを維持します — SDK は既定でこれを行います。無効にしないでください。バースト性のあるワークロードにはアダプティブリトライモードを使いましょう。
4. ホットパーティションを解消します — キーのカーディナリティを上げる、ホットキーを書き込みシャーディングするなどして、負荷をパーティション間に分散させます。
5. 一括ジョブを絞り、ホットな読み取りをキャッシュ（DAX やアプリのキャッシュ）して読み取り圧を逃がします。

よくある質問

ProvisionedThroughputExceededException はどう直せばよいですか？ テーブルやインデックスが提供できるより速く読み書きしています。テーブルをオンデマンドキャパシティに切り替え、プロビジョニング済みの RCU/WCU を引き上げる（または Auto Scaling を有効にする）、SDK 既定の指数バックオフ付きリトライを維持する、そして単一のパーティションキーがホットにならないようトラフィックを分散させてください。

再現方法

テーブルを 1 RCU でプロビジョニングし、4 KB 弱のアイテムを1つ put して、それを強整合読み取りでタイトループで読み戻します。

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

発生までに49回の読み取りを要しました。 作りたてのテーブルで、SDK のリトライを無効にした状態です。この数字こそが面白いところです。1 RCU のテーブルは2回目のリクエストで失敗したりしません。DynamoDB がまず蓄積したバーストキャパシティを貸してくれるからです — つまり早めに切り上げた負荷テストは、健全でないテーブルを健全だと報告します。この錯覚のもう半分は SDK です。SDK は既定でスロットリングされたリクエストを代わりにリトライします。上のようにリトライを無効にしないと、このエラーはレイテンシの問題になるまで見えないままです。

関連するエラー

• ThrottlingException — アカウント/コントロールプレーンのレート制限。
• Throttled despite spare capacity (hot partition) — 1つのパーティションキーがトラフィックを吸い込んでいる。
• On-demand throughput exceeded — オンデマンドモードでの同等物。
• ItemCollectionSizeLimitExceededException
• Code example: BatchWriteItem in Node.js — UnprocessedItems のバックオフ付きリトライパターン。
• 学習: オンデマンドとプロビジョンド · ホットパーティション

参考資料

• Error handling with DynamoDB — Amazon DynamoDB Developer Guide
• Troubleshooting throttling in Amazon DynamoDB — Amazon DynamoDB Developer Guide
• Best practices for designing and using partition keys effectively in DynamoDB — Amazon DynamoDB Developer Guide
• Quotas in Amazon DynamoDB — Amazon DynamoDB Developer Guide

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。

2026-07-26 に、1 RCU でプロビジョニングし SDK のリトライを無効にしたテーブルで、us-east-1 の実稼働 DynamoDB サービスに対し boto3 1.43.56 で再現しました — 上記の出力はそのままの逐語です。