# 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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/CommonErrors.html). **Topics** + [Componentes de erros](#Programming.Errors.Components) + [Erros transacionais](#Programming.Errors.TransactionalErrors) + [Mensagens e códigos de erro](#Programming.Errors.MessagesAndCodes) + [Tratamento de erros na aplicação](#Programming.Errors.Handling) + [Repetições de erro e recuo exponencial](#Programming.Errors.RetryAndBackoff) + [Operações em lote e tratamento de erros](#Programming.Errors.BatchOperations) ## 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](transaction-apis.md#transaction-conflict-handling) ## 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](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) 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](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) 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](LSI.md#LSI.ItemCollections). 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](Programming.LowLevelAPI.md). 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](https://console.aws.amazon.com/cloudwatch/home)*. O erro inclui uma lista de campos `ThrottlingReason` que apresenta um contexto específico sobre o motivo do controle de utilização, seguindo o formato `ResourceType+OperationType+LimitType` (p. ex., `TableReadProvisionedThroughputExceeded`) e o ARN do recurso afetado. Isso ajuda a identificar qual recurso está sofrendo controle de utilização (tabela ou índice), qual tipo de operação acionou o controle (leitura ou gravação) e o limite específico que foi excedido (nesse caso, capacidade provisionada). Para ter mais informações sobre como diagnosticar e resolver problemas de controle de utilização, consulte [Diagnosticar o controle de utilização](throttling-diagnosing-workflow.md). 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](#Programming.Errors.RetryAndBackoff). OK para tentar novamente? Sim **ReplicatedWriteConflictException** Mensagem: *um ou mais itens desta solicitação estão sendo modificados por uma solicitação em outra região.* Exemplo: uma operação de gravação foi solicitada para um item em uma tabela global multirregional fortemente consistente (MRSC) que está sendo modificada atualmente por uma solicitação em outra região. 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](https://aws.amazon.com/support)*. O erro inclui uma lista de campos `ThrottlingReason` que apresenta um contexto específico sobre o motivo do controle de utilização, seguindo o formato `ResourceType+OperationType+LimitType` (p. ex., `TableWriteAccountLimitExceeded` ou `IndexReadAccountLimitExceeded`) e o ARN do recurso afetado. Isso ajuda você a identificar qual recurso está sofrendo controle de utilização (tabela ou índice), qual tipo de operação acionou o controle (leitura ou gravação) e se você excedeu as cotas de serviço em nível de conta. Para ter mais informações sobre como diagnosticar e resolver problemas de controle de utilização, consulte [Diagnosticar o controle de utilização](throttling-diagnosing-workflow.md). 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\$1EXCEPTION. Essa exceção poderá ser retornada se você executar operações de API de [plano de controle](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.API.html#HowItWorks.API.ControlPlane) 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](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.API.html#HowItWorks.API.DataPlane) se a sua taxa de solicitação for muito alta. Para saber mais sobre escalabilidade sob demanda, consulte [Throughput inicial e propriedades de escalabilidade](on-demand-capacity-mode.md#on-demand-capacity-mode-initial). O erro inclui uma lista de campos `ThrottlingReason` que apresenta um contexto específico sobre o motivo do controle de utilização, seguindo o formato `ResourceType+OperationType+LimitType` (p. ex., `TableReadKeyRangeThroughputExceeded` ou `IndexWriteMaxOnDemandThroughputExceeded`) e o ARN do recurso afetado. Essas informações ajudam a identificar qual recurso está sofrendo controle de utilização (tabela ou índice), qual tipo de operação acionou o controle (leitura ou gravação) e o limite específico que foi excedido (limites de partição ou throughput máximo sob demanda). Para ter mais informações sobre como diagnosticar e resolver problemas de controle de utilização, consulte [Diagnosticar o controle de utilização](throttling-diagnosing-workflow.md). 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](https://status.aws.amazon.com/) 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?](https://aws.amazon.com/premiumsupport/knowledge-center/dynamodb-http-5xx-errors/) **InternalServerError (HTTP 500)** O DynamoDB não pôde processar a solicitação. OK para tentar novamente? Sim 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 [Exemplo de expressão de condição do DynamoDB na CLI](Expressions.ConditionExpressions.md) 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`](transaction-apis.md#transaction-apis-txwriteitems), 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 para 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. Para obter recomendações detalhadas para abordar cenários específicos de controle de utilização, consulte a seção [Solução de problemas de controle de utilização do DynamoDB](TroubleshootingThrottling.md). 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](http://www.awsarchitectureblog.com/2015/03/backoff.html). ## 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. **nota** Como alguns SDKs da AWS oferecem clientes de nível superior que lidam automaticamente com novas tentativas de itens não processados, você não precisa implementar essa lógica de repetição por conta própria. Por exemplo: **Java**: o [Cliente Aprimorado do DynamoDB](DynamoDBEnhanced.md) no AWS SDK para Java v2 e o [DynamoDBMapper](DynamoDBMapper.md) na v1 reexecutam automaticamente os itens não processados ao realizar operações em lote. **Python**: o recurso de tabela `batch_writer` do Boto3 lida implicitamente com novas tentativas de itens não processados para operações de gravação em lote. Para obter mais informações, consulte [Usar o recurso de tabela batch\$1writer](programming-with-python.md#programming-with-python-batch-writer). Se estiver usando um cliente de baixo nível ou um SDK que não oferece esse comportamento, você deverá implementar a lógica de novas tentativas por conta própria conforme descrito acima.