DynamoDB ThrottlingException

TL;DR — Sua taxa de solicitação excedeu um limite. É retentável – faça backoff e tente novamente (o SDK faz isso por padrão). Se persistir, você está chamando um control-plane API (CreateTable, UpdateTable, DescribeTable) com muita frequência ou atingindo um limite no nível da conta.

O que significa

ThrottlingException: Rate of requests exceeds the allowed throughput.

ThrottlingException (e o RequestLimitExceeded relacionado) sinaliza um limite de taxa que não é a configuração RCU/WCU da própria tabela provisionada. Ele volta como HTTP 400 e é possível tentar novamente. É mais comum em operações de control-plane executadas muito rapidamente e, para tabelas on-demand, pode ser retornado para qualquer operação de data-plane quando a taxa de solicitação é muito alta (inclusive quando você excede uma taxa de transferência máxima on-demand configurada). O erro carrega campos ThrottlingReason nomeando o recurso limitado e o limite que foi atingido.

Por que isso acontece

Consultar APIs de control-plane repetidamente — chamando DescribeTable, ListTables, UpdateTable em um loop apertado (por exemplo, aguardando que uma tabela se torne ACTIVE).
Criar/excluir muitas tabelas rapidamente — as operações simultâneas do control-plane são limitadas (não mais que 500 tabelas/indexes em CREATING/UPDATING/DELETING de uma só vez).
Uma taxa de transferência máxima on-demand configurada — excedendo MaxReadRequestUnits/MaxWriteRequestUnits em uma tabela on-demand ou GSI retorna ThrottlingException.
Uma explosão repentina em uma tabela on-demand — novas tabelas começam em 4.000 escritas/s e 12.000 leituras/s, e exceder o dobro do pico anterior em 30 minutos pode acelerar até que o DynamoDB seja dimensionado.

Como corrigir

Tente novamente com espera exponencial + jitter — os SDKs AWS fazem isso automaticamente; mantenha as novas tentativas habilitadas e considere o modo de nova tentativa adaptativo.
Pare os APIs do control-plane de pesquisa rigorosa. Use waiters (waitUntilTableExists) que pesquisam em uma programação sensata em vez de um hot loop.
Gravações em lote e ritmo no data-plane. Aumente os carregamentos em massa gradualmente para que a capacidade on-demand possa ser dimensionada com você.
Distribua as operações de tabela ao longo do tempo, em vez de criar dezenas de uma vez.
Verifique ThrottlingReason na resposta. Ele nomeia o recurso e o limite limitados — aceleradores de control-plane versus aceleradores de data-plane on-demand precisam de correções diferentes.

Exemplo

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {waitUntilTableExists} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({});
//  a waiter polls on a backoff schedule — not a tight DescribeTable loop
await waitUntilTableExists({client, maxWaitTime: 120}, {TableName: 'Orders'});

FAQ

ThrottlingException é o mesmo que ProvisionedThroughputExceededException? Não. ProvisionedThroughputExceededException é o erro do data-plane por exceder a capacidade provisionada de uma tabela. ThrottlingException é mais comum em operações de control-plane (CreateTable, UpdateTable, DescribeTable), que têm limites baixos para toda a conta e em rajadas de volume muito alto.

Como faço para corrigir uma ThrottlingException DynamoDB? Tente novamente com espera exponencial e jitter — os SDKs AWS fazem isso automaticamente. Interrompa os APIs do control-plane de pesquisa restrita (use garçons como waitUntilTableExists), aumente gradualmente as cargas em massa para que a capacidade on-demand possa ser dimensionada com você e distribua as operações da tabela ao longo do tempo.

Confira o tamanho no DynoTable

Quando a otimização do control-plane bloqueia a configuração da tabela, use DynoTable para navegar nas tabelas existentes em vez de pesquisar DescribeTable em um loop - abra tabelas com ⌘K após uma única atualização. Para cargas em massa que acionam a limitação on-demand, dimensione o tráfego com a calculadora de preços antes de aumentar.

Alternar perfis com ⌘P; Testar conexão em Configurações → Perfis confirma a conta. Consulte Conectar ao AWS e Instalar.

Fontes

Tratamento de erros com DynamoDB — ThrottlingException (verificado em 13/07/2026)
Solução de problemas de limitação no Amazon DynamoDB (verificado em 13/07/2026)

Erros relacionados

ProvisionedThroughputExceededException — limitação de capacidade por tabela.
RequestLimitExceeded — a cota de taxa de solicitação da conta.
Taxa de transferência on-demand excedida — as tabelas on-demand ainda podem ser limitadas.
ResourceInUseException — tabela ocupada/já existe.
Aprenda: on-demand vs. provisionado

Referências

Última verificação em 13/07/2026 em relação à documentação oficial do AWS vinculada acima.