Provided list of item keys contains duplicates (BatchGetItem)

TL;DR — Seu array Keys do BatchGetItem para uma tabela lista a mesma chave primária mais de uma vez. O DynamoDB exige que toda chave em um lote seja única e rejeita a requisição inteira — ele não descarta a duplicata silenciosamente. De-duplique a lista de chaves antes de enviá-la.

O que significa

ValidationException: Provided list of item keys contains duplicates

BatchGetItem lê até 100 itens entre tabelas. Dentro da lista Keys de uma única tabela, cada entrada precisa ser uma chave primária distinta (chave de partição, ou partição + ordenação para tabelas compostas). Duas entradas que resolvem para a mesma chave disparam este HTTP 400 ValidationException, e a chamada inteira falha — nenhum item é retornado. Não é retentável como está.

Por que isso acontece

A mesma chave aparece duas vezes na lista — frequentemente porque IDs foram coletados de múltiplas fontes e nunca mesclados.
Uma lista de chaves gerada (por exemplo, mapear uma lista de registros para chaves) onde a origem tinha linhas duplicadas.
Confusão de chave composta — duas entradas compartilham a chave de partição mas você esqueceu que a chave de ordenação difere; ou ambas são genuinamente idênticas.
Diferenças de maiúsculas / tipo mascarando uma duplicata real — duas chaves que fazem marshal para o mesmo valor.
Pipelines de carga (Glue, ETL customizado) que agrupam chaves em lotes sem um passo de de-duplicação.

Como corrigir

De-duplique antes da chamada. Chaveie cada entrada por uma string estável e mantenha uma:

const seen = new Set();
const keys = raw.filter((k) => {
  const id = `${k.pk.S}#${k.sk?.S ?? ''}`;
  if (seen.has(id)) return false;
  seen.add(id);
  return true;
});

Lembre-se de que um lote é um conjunto, não uma sacola — você só precisa de uma leitura por chave; o item volta uma vez independentemente.
Divida em 100 chaves por BatchGetItem e trate UnprocessedKeys na resposta (throttling, não duplicatas).
Proteja seu ETL/loader com a mesma de-duplicação para que o problema não possa recorrer mais acima.
Registre o tamanho da lista de chaves antes de cada lote. Quando duplicatas escapam, o erro não informa nenhum índice — seus logs precisam mostrar qual fonte a montante repetiu um ID.

Caminho no DynoTable

Antes de fazer leituras em lote de chaves na produção, detecte duplicatas no DynoTable — abra a tabela com ⌘K, filtre pelos IDs que você planeja buscar e confirme que cada chave primária aparece uma única vez. A lista de itens mostra as chaves de partição e de ordenação lado a lado, então colisões de chave composta ficam evidentes.

Ao levar a leitura para o código, use o Query Builder para prototipar primeiro leituras de chave única e depois escalar para um BatchGetItem dividido em blocos. Troque de perfil com ⌘P; configure-os em Configurações → Perfis com Testar conexão. Consulte Conectar ao AWS e Instalar.

Fontes

BatchGetItem — Amazon DynamoDB API Reference (verificado em 13/07/2026)
Error handling with DynamoDB (verificado em 13/07/2026)

Erros relacionados

Provided list of item keys contains duplicates (BatchWriteItem) — a mesma regra no caminho de escrita.
ValidationException (visão geral)
Exemplo de código: BatchGetItem in Node.js — uma leitura em lote correta e dividida em blocos para adaptar.
Aprenda: Batch operations

Referências

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