InternalServerError (HTTP 500)

TL;DR — O DynamoDB não conseguiu processar a requisição; a falha é do lado do serviço e tentar novamente é a resposta documentada — a AWS afirma que esses erros são esperados durante a vida de uma tabela e requisições que falharam podem ser tentadas novamente imediatamente. A única sutileza: um 500 em uma escrita é ambíguo (ela pode ter sido bem-sucedida ou falhado), então releia o item ou use um padrão idempotente antes de reaplicá-la às cegas.

O que significa

InternalServerError: The server encountered an internal error trying to
fulfill the request.

Ao contrário dos erros da série 400 neste hub, um 5xx não significa que sua requisição estava errada — significa que o DynamoDB atingiu uma falha interna ao tratá-la. O ServiceUnavailable (HTTP 503) relacionado sinaliza um problema temporário de disponibilidade e é igualmente retentável. Os AWS SDKs já tentam ambos automaticamente com backoff exponencial, então você tipicamente só verá um 500 aparecer depois que os retries do SDK se esgotaram.

Por que acontece

Falhas transitórias do lado do serviço — a AWS documenta que erros internos ocasionais são esperados durante a vida de uma tabela; eles não são causados pela forma da sua requisição.
Um evento genuíno de serviço — se respostas 5xx persistem ao longo dos retries, verifique o AWS Health Dashboard para um problema operacional na sua Region.

Como corrigir

Tente novamente com backoff exponencial — ou simplesmente deixe o SDK fazer isso; todo AWS SDK tenta novamente respostas 5xx automaticamente. Só após falha persistente você deve tratá-lo como um incidente.
Trate a ambiguidade de escrita — um 500 em PutItem/UpdateItem/DeleteItem pode ter sido aplicado. As opções documentadas:
- releia o estado do item antes de tentar novamente, e/ou
- proteja o retry com uma condition expression para que ele permaneça correto independentemente de a primeira tentativa ter aterrissado, por exemplo, uma verificação de versão:
```
ConditionExpression: 'version = :expected',
ExpressionAttributeValues: {':expected': {'N': '7'}}
```
- use TransactWriteItems com um ClientRequestToken quando a idempotência é um requisito rígido — tentativas duplicadas dentro da janela do token contam uma vez.
Um 500 em TransactWriteItems é seguro para tentar novamente como está — a transação ou foi commitada ou não foi; o token deduplica.
Escale apenas quando persistir — 5xx sustentado ao longo de minutos é um problema de serviço: verifique o health dashboard e abra um caso de suporte com o RequestId das respostas que falharam.

Após uma escrita ambígua, olhe o que está de fato armazenado antes de reexecutar seu job — o app desktop DynoTable mostra o estado ao vivo do item num relance, e a calculadora de preços do DynamoDB ajuda a dimensionar o tráfego de retry se você estiver reprocessando um lote.

Erros relacionados

ThrottlingException — o 400 retentável que parece similar mas tem causa de capacidade.
TransactionInProgressException — tempo de retry em transações.
Aprenda: DynamoDB consistency

Referências

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