DynamoDB ProvisionedThroughputExceededException

TL;DR — Você está lendo/escrevendo mais rápido do que a tabela ou índice consegue servir. Mude a tabela para capacidade on-demand, aumente o RCU/WCU provisionado (ou habilite auto-scaling), mantenha os retries de backoff exponencial padrão do SDK, e espalhe o tráfego para que uma chave de partição não fique quente.

O que significa

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

Em uma tabela de capacidade provisionada, você excedeu as unidades de capacidade de leitura/escrita — seja no geral, ou (mais frequentemente) em uma única partição. É um HTTP 400 mas, ao contrário de um ValidationException, ele é retentável: os AWS SDKs o tentam novamente automaticamente com backoff exponencial, então ocorrências ocasionais são normais. Ocorrências persistentes significam subprovisionamento real ou uma chave quente. O erro carrega campos ThrottlingReason (por exemplo, TableReadProvisionedThroughputExceeded) mais o ARN do recurso afetado, para que você saiba qual tabela ou índice sofreu throttle e em qual tipo de operação.

Por que isso acontece

Capacidade subprovisionada para o tráfego real.
Uma partição quente — tráfego concentrado em uma chave de partição, então a parcela de capacidade de uma única partição se esgota enquanto a tabela parece subutilizada no geral.
Tráfego em picos mais rápido do que o auto scaling consegue reagir — ele ajusta a capacidade em resposta às métricas de capacidade consumida, então um salto repentino gera throttle antes de o aumento entrar em vigor.
Um scan grande ou importação em massa consumindo toda a capacidade de uma vez.
Um GSI cuja capacidade é menor que a taxa de escrita — um GSI com throttle faz throttle na tabela base.

Como corrigir

Mude para capacidade on-demand se o tráfego é imprevisível — ele escala automaticamente e este erro efetivamente desaparece (você paga por requisição em vez disso).
Aumente o RCU/WCU provisionado ou habilite auto-scaling com uma utilização alvo sensata se você continuar no provisionado.
Mantenha retries de backoff exponencial — o SDK faz isso por padrão; não o desabilite. Use o modo de retry adaptativo para cargas com rajadas.
Corrija a partição quente — aumente a cardinalidade da chave / faça write-sharding da chave quente para que a carga se espalhe pelas partições.
Limite a taxa dos jobs em massa e cacheie leituras quentes (DAX ou um cache de app) para aliviar a pressão de leitura.

FAQ

Como corrijo ProvisionedThroughputExceededException? Você está lendo ou escrevendo mais rápido do que a tabela ou índice consegue servir. Mude a tabela para capacidade on-demand, aumente o RCU/WCU provisionado (ou habilite auto-scaling), mantenha os retries de backoff exponencial padrão do SDK, e espalhe o tráfego para que uma única chave de partição não fique quente.

Reproduza

Provisione uma tabela com 1 RCU, coloque um item pouco abaixo de 4 KB, e então leia-o de volta com consistência forte em um loop apertado:

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)

Saída real:

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

Foram necessárias 49 leituras para disparar, em uma tabela recém-criada com os retries do SDK desativados. Esse número é a parte interessante: uma tabela de 1 RCU não falha na segunda requisição, porque o DynamoDB primeiro te empresta a capacidade de burst acumulada — então um teste de carga que para cedo demais vai reportar como saudável uma tabela que não é. A outra metade da ilusão é o SDK, que tenta novamente as requisições com throttle por você por padrão; desative os retries como acima, ou este erro fica invisível até virar um problema de latência.

Erros relacionados

ThrottlingException — limites de taxa de conta/control-plane.
Throttled despite spare capacity (hot partition) — uma chave de partição absorvendo o tráfego.
On-demand throughput exceeded — o equivalente do modo on-demand.
ItemCollectionSizeLimitExceededException
Exemplo de código: BatchWriteItem in Node.js — o padrão de retry-com-backoff de UnprocessedItems.
Aprenda: On-demand vs provisioned · Hot partitions

Referências

Verificado pela última vez em 2026-07-13 contra a documentação oficial da AWS vinculada acima.

Reproduzido em 2026-07-26 no serviço DynamoDB real em us-east-1 via boto3 1.43.56, em uma tabela provisionada com 1 RCU e os retries do SDK desativados — a saída acima é literal.