Tratamento de erros com o DynamoDB

Esta seção descreve erros de runtime e como lidar com eles. Ela também descreve códigos e mensagens de erro que são específicos para o Amazon DynamoDB. Para obter uma lista de erros comuns que se aplicam a todos os serviços da AWS, consulte Gerenciamento de acesso.

Componentes de erros

Quando seu programa envia uma solicitação, o DynamoDB tenta processá-la. Se a solicitação for bem-sucedida, o DynamoDB retornará um código de status HTTP de êxito (200 OK), juntamente com os resultados da operação solicitada.

Se a solicitação falhar, o DynamoDB retornará um erro. Cada erro tem três componentes:

• Um código de status HTTP (como 400).

• Um nome de exceção (como ResourceNotFoundException).

• Uma mensagem de erro (como Requested resource not found: Table: tablename not found).

Os AWS SDKs cuidam da propagação de erros para sua aplicação para que você possa tomar as medidas apropriadas. Por exemplo, em um programa Java, você pode escrever a lógica try-catch para lidar com um ResourceNotFoundException.

Se você não estiver usando um AWS SDK, será necessário analisar o conteúdo da resposta de baixo nível do DynamoDB. Veja a seguir um exemplo dessa resposta.

HTTP/1.1 400 Bad Request
x-amzn-RequestId: LDM6CJP8RMQ1FHKSC1RBVJFPNVV4KQNSO5AEMF66Q9ASUAAJG
Content-Type: application/x-amz-json-1.0
Content-Length: 240
Date: Thu, 15 Mar 2012 23:56:23 GMT

{"__type":"com.amazonaws.dynamodb.v20120810#ResourceNotFoundException",
"message":"Requested resource not found: Table: tablename not found"}

Erros transacionais

Para obter informações sobre erros transacionais, consulte Tratamento de conflitos em transações com o DynamoDB

Mensagens e códigos de erro

Veja a seguir uma lista de exceções retornadas pelo DynamoDB, agrupadas por código de status HTTP. Se OK para tentar novamente? for Sim, você poderá enviar a mesma solicitação novamente. Se OK to retry? (OK tentar novamente?) for No (Não), você deverá corrigir o problema no lado do cliente antes de enviar uma nova solicitação.

Código de status HTTP 400

Um código de status HTTP 400 indica um problema com sua solicitação, como falha de autenticação, parâmetros necessários ausentes ou limite excedido do throughput provisionado de uma tabela. Será necessário corrigir o problema no aplicativo antes de enviar a solicitação novamente.

AccessDeniedException

Mensagem: Acesso negado.

The client did not correctly sign the request. Se estiver usando um AWS SDK, as solicitações serão assinadas para você automaticamente. Do contrário, acesse o Processo de assinatura do Signature versão 4 na Referência geral da AWS.

OK para tentar novamente? Não

ConditionalCheckFailedException

Mensagem: A solicitação condicional falhou.

Você especificou uma condição avaliada como false. Por exemplo, você pode ter tentado realizar uma atualização condicional em um item, mas o valor real do atributo não correspondeu ao valor esperado na condição.

OK para tentar novamente? Não

IncompleteSignatureException

Mensagem: A assinatura da solicitação não atende aos padrões da AWS.

A assinatura da solicitação não incluía todos os componentes necessários. Se estiver usando um AWS SDK, as solicitações serão assinadas para você automaticamente. Do contrário, acesse o Processo de assinatura do Signature versão 4 na Referência geral da AWS.

OK para tentar novamente? Não

ItemCollectionSizeLimitExceededException

Mensagem: Tamanho da coleção excedido.

Para uma tabela com um índice secundário local, um grupo de itens com o mesmo valor de chave de partição excedeu o limite de tamanho máximo de 10 GB. Para obter mais informações sobre coleções de itens, consulte Conjuntos de itens em índices secundários locais.

OK para tentar novamente? Sim

LimitExceededException

Mensagem: Muitas operações para um assinante específico.

Existem muitas operações simultâneas no plano de controle. O número cumulativo de tabelas e índices no estado CREATING, DELETING ou UPDATING não pode exceder 500.

OK para tentar novamente? Sim

MissingAuthenticationTokenException

Mensagem: A solicitação deve conter um ID de chave de acesso válido (registrado) na AWS.

A solicitação não incluía o cabeçalho de autorização necessário ou estava mal formada. Consulte API de baixo nível do DynamoDB.

OK para tentar novamente? Não

ProvisionedThroughputExceededException

Mensagem: You exceeded your maximum allowed provisioned throughput for a table or for one or more global secondary indexes. (Você excedeu seu throughput provisionado máximo permitida para uma tabela ou para um ou mais índices secundários globais.) Para visualizar métricas de performance para throughput provisionado versus throughput consumido, abra o console do Amazon CloudWatch.

Exemplo: Sua taxa de solicitação é muito alta. Os AWS SDKs para o DynamoDB realizam automaticamente novas tentativas de envio de uma mesma solicitação que recebe essa exceção. Sua solicitação em algum momento terá êxito, a menos que a fila de novas tentativas seja muito grande para concluir. Reduza a frequência de solicitações usando Repetições de erro e recuo exponencial.

OK para tentar novamente? Sim

RequestLimitExceeded

Mensagem: Throughput exceeds the current throughput limit for your account (o throughput excede o limite de throughput atual de sua conta). Para solicitar um aumento de limite, entre em contato com o AWS Support em https://aws.amazon.com/support.

Exemplo: a taxa de solicitações sob demanda excede o throughput permitido da conta e a tabela não pode ser escalada além disso.

OK para tentar novamente? Sim

ResourceInUseException

Mensagem: O recurso que você está tentando alterar está em uso.

Exemplo: você tentou recriar uma tabela existente ou excluir uma tabela atualmente no estado CREATING.

OK para tentar novamente? Não

ResourceNotFoundException

Mensagem: O recurso solicitado não foi encontrado.

Exemplo: a tabela que está sendo solicitada não existe ou está há pouco tempo no estado CREATING.

OK para tentar novamente? Não

ThrottlingException

Mensagem: A taxa de solicitações excede o throughput permitido.

Essa exceção é retornada como uma resposta da AmazonServiceException com um código de status THROTTLING_EXCEPTION. Essa exceção poderá ser retornada se você executar operações de API de plano de controle muito rapidamente.

Para as tabelas que usam o modo sob demanda, essa exceção poderá ser retornada para qualquer operação de API do plano de dados se a sua taxa de solicitação for muito alta. Para saber mais sobre dimensionamento sob demanda, consulte Tráfego de pico e propriedades de dimensionamento

OK para tentar novamente? Sim

UnrecognizedClientException

Mensagem: o ID da chave de acesso ou o token de segurança é inválido.

A assinatura da solicitação está incorreta. A causa mais provável é um ID de chave de acesso da AWS ou uma chave secreta inválidos.

OK para tentar novamente? Sim

ValidationException

Mensagem: varia dependendo do erro específico encontrado

Esse erro pode ocorrer por vários motivos, como um parâmetro necessário ausente, um valor fora do intervalo ou tipos de dados incompatíveis. A mensagem de erro contém detalhes sobre a parte específica da solicitação que causou o erro.

OK para tentar novamente? Não

Código de status HTTP 5xx

Um código de status HTTP 5xx indica um problema que deve ser resolvido pela AWS. Pode ser um erro transitório e, nesse caso, é possível repetir a solicitação até que ela tenha êxito. Caso contrário, acesse o AWS Service Health Dashboard para ver se há problemas operacionais com o serviço.

Para obter mais informações, consulte Como resolver erros de HTTP 5xx no Amazon DynamoDB?

InternalServerError (HTTP 500)

O DynamoDB não pôde processar a solicitação.

OK para tentar novamente? Sim

nota

Você pode encontrar erros de servidor internos enquanto trabalha com itens. Esses são esperados durante a vida útil de uma tabela. Todas as solicitações com falha podem ser repetidas imediatamente.

Quando você recebe um código de status 500 em uma operação de gravação, a operação pode ter sido concluída com sucesso ou com erro. Se a operação de gravação for uma solicitação TransactWriteItem, a operação pode ser repetida. Se a operação de gravação for uma solicitação de gravação de um único item, como PutItem, UpdateItem ou DeleteItem, sua aplicação deve ler o estado do item antes de tentar novamente a operação e/ou usar Expressões de condição para garantir que o item permaneça em um estado correto após tentar novamente, independentemente de a operação anterior ter sido concluída com sucesso ou com erro. Se a idempotência for um requisito para a operação de gravação, use TransactWriteItem, que é compatível com solicitações idempotentes, especificando automaticamente um ClientRequestToken para eliminar ambiguidades em várias tentativas de executar a mesma ação.

ServiceUnavailable (HTTP 503)

O DynamoDB está indisponível no momento. (Esse estado deve ser temporário.)

OK para tentar novamente? Sim

Tratamento de erros na aplicação

Para que seu aplicativo seja executado sem problemas, é necessário adicionar uma lógica para detectar erros e reagir a eles. As abordagens comuns incluem o uso de blocos try-catch ou de uma instrução if-then.

Os AWS SDKs realizam por conta própria novas tentativas e verificações de erros. Se você se deparar com um erro enquanto usa um dos AWS SDKs, o código de erro e sua descrição poderão ajudar a solucioná-lo.

Você também deve ver um Request ID na resposta. O Request ID pode ser útil se você precisa trabalhar com o AWS Support para diagnosticar um problema.

Repetições de erro e recuo exponencial

Vários componentes em uma rede, como servidores DNS, switches, load balancers e outros, podem gerar erros em qualquer momento do ciclo de vida de uma determinada solicitação. A técnica usual para lidar com essas respostas de erro em um ambiente de rede é implementar novas tentativas no aplicativo cliente. Essa técnica aumenta a confiabilidade da aplicação.

Cada AWS SDK implementa a lógica de novas tentativas automaticamente. Você pode modificar os parâmetros de novas tentativas de acordo com as suas necessidades. Por exemplo, considere um aplicativo Java que exija uma estratégia rápida contra falhas, sem permitir novas tentativas em caso de erro. Com o AWS SDK for Java, você poderia usar a classe ClientConfiguration e fornecer um valor maxErrorRetry de 0 para desativar as novas tentativas. Para obter mais informações, consulte a documentação do AWS SDK para sua linguagem de programação.

Se não estiver usando um AWS SDK, você deverá tentar novamente as solicitações originais que recebem erros do servidor (5xx). No entanto, erros de cliente (4xx, diferente de ThrottlingException ou ProvisionedThroughputExceededException) indicam que você precisa revisar a solicitação para corrigir o problema antes de tentar novamente.

Além de novas tentativas simples, cada AWS SDK implementa um algoritmo de recuo exponencial para um melhor controle de fluxo. O conceito por detrás do recuo exponencial é usar esperas progressivamente mais longas entre as novas tentativas para respostas de erro consecutivas. Por exemplo, até 50 milissegundos antes da primeira nova tentativa, até 100 milissegundos antes da segundo, até 200 milissegundos antes da terceira e assim por diante. No entanto, depois de um minuto, se a solicitação não tiver sido bem-sucedida, talvez o problema esteja relacionado ao tamanho da solicitação que exceda o throughput provisionado e não à taxa de solicitação. Defina um tempo de interrupção de cerca de um minuto para o número máximo de novas tentativas. Se a solicitação não for bem-sucedida, investigue suas opções de throughput provisionado.

nota

Os AWS SDKs implementam uma lógica de novas tentativas automáticas e de recuo exponencial.

A maioria dos algoritmos de recuo exponencial usam variação (atraso randomizado) para evitar colisões sucessivas. Como você não está tentando evitar essas colisões nesses casos, não precisa usar esse número aleatório. No entanto, se você usar clientes simultâneos, a variação pode ajudar suas solicitações a serem bem-sucedidas mais depressa. Para obter mais informações, consulte a postagem no blog sobre Recuo exponencial e variação.

Operações em lote e tratamento de erros

A API de baixo nível do DynamoDB oferece suporte a operações em lote para leituras e gravações. BatchGetItem lê os itens de uma ou mais tabelas, e BatchWriteItem insere ou exclui itens de uma ou mais tabelas. Essas operações em lote são implementadas como wrappers em torno de outras operações do DynamoDB que não são feitas em lote. Em outras palavras, BatchGetItem invoca GetItem uma vez para cada item do lote. Da mesma forma, BatchWriteItem invoca DeleteItem ou PutItem, conforme apropriado, para cada item do lote.

Uma operação em lote pode tolerar a falha de solicitações individuais no lote. Por exemplo, considere uma solicitação BatchGetItem para ler cinco itens. Mesmo se algumas das solicitações GetItem subjacentes falharem, isso não faz com que toda a operação BatchGetItem falhe. Entretanto, se todas as cinco operações de leitura falharem, todo o BatchGetItem falhará.

As operações em lote retornam informações sobre solicitações individuais que apresentam falhas, para que você possa diagnosticar o problema e repetir a operação. Para BatchGetItem, as tabelas e chaves primárias em questão são retornadas no valor de UnprocessedKeys da resposta. Para BatchWriteItem, informações semelhantes são retornadas em UnprocessedItems.

A causa mais provável de uma falha de leitura ou gravação é a controle de utilização. Para BatchGetItem, uma ou mais das tabelas na solicitação em lote não tem capacidade de leitura provisionada suficiente para dar suporte à operação. Para BatchWriteItem, uma ou mais das tabelas não tem capacidade de gravação provisionada suficiente.

Se o DynamoDB retornar itens não processados, você deverá repetir a operação em lote nesses itens. No entanto, recomendamos que você use um algoritmo de recuo exponencial. Se você repetir a operação em lote imediatamente, solicitações subjacentes de leitura ou gravação ainda poderão falhar devido ao controle de utilização nas tabelas individuais. Se você atrasar a operação em lote usando o recuo exponencial, as solicitações individuais no lote terão muito mais chances de sucesso.