As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Comportamento de repetição

Quando uma solicitação para um AWS service (Serviço da AWS) falha devido a um erro transitório ou limitação, o SDK pode repetir a solicitação automaticamente. Esta página aborda como configurar novas tentativas e como elas funcionam internamente.

Configurando novas tentativas

Você controla qual estratégia de repetição o SDK usa e quantas vezes ele tenta novamente.

Escolhendo um modo de nova tentativa

O modo de nova tentativa determina como o SDK se comporta quando uma solicitação falha. Três modos estão disponíveis: padrão , adaptável e legado.

Modo padrão (padrão)

O modo padrão repete as solicitações que falharam usando o recuo exponencial com instabilidade. Ele usa atrasos mais curtos para erros transitórios (como tempos limite de rede) e atrasos mais longos para erros de limitação (como). ThrottlingException

O modo padrão inclui uma cota de novas tentativas, um conjunto de tokens que deduz tokens para cada nova tentativa e reabastece os tokens quando as solicitações são bem-sucedidas. Quando os tokens disponíveis se esgotam, o SDK retorna o erro sem tentar novamente, então seu aplicativo falha rapidamente em vez de esperar por novas tentativas que provavelmente não serão bem-sucedidas. Isso também ajuda as interrupções do serviço a serem resolvidas mais rapidamente, reduzindo o tráfego de novas tentativas. Durante a operação normal, a cota permanece cheia e não tem efeito. A cota de novas tentativas nunca atrasa nem bloqueia a solicitação inicial. Somente novas tentativas são afetadas. Para obter detalhes, consulte Cota de repetição (bucket de tokens).

Use o modo padrão, a menos que você tenha um motivo específico para escolher outro modo.

Modo adaptativo

O modo adaptativo inclui tudo no modo padrão, além de um limitador de taxa do lado do cliente. O limitador de taxa rastreia as respostas de limitação e ajusta a taxa na qual o SDK envia solicitações. Ao contrário do modo padrão, o modo adaptativo pode atrasar ou bloquear a solicitação inicial, não apenas novas tentativas, quando a limitação é detectada.

O limitador de taxa opera por instância de cliente do SDK. Todas as solicitações de um cliente compartilham o mesmo limite de taxa, independentemente de qual operação de API ou recurso elas almejam.

Quando usar o modo adaptativo:

Quando não usar o modo adaptativo:

O modo adaptativo não é recomendado como padrão geral.

Modo legado

O modo legado é o comportamento de nova tentativa que cada SDK usou antes da introdução do modo padrão. Ela não inclui uma cota de repetição padronizada. Alguns SDKs (como Java) tinham suas próprias implementações de cota de repetição no modo legado, mas o comportamento não é consistente entre os SDKs. Sem uma cota padronizada, o cliente continua tentando novamente a todo vapor durante interrupções no serviço. Isso vincula threads e conexões em solicitações que provavelmente não serão bem-sucedidas, ao mesmo tempo em que adiciona carga que pode atrasar a recuperação do serviço.

O modo legado varia entre os SDKs. A contagem de tentativas, o tempo de recuo, os conjuntos de erros que podem ser repetidos e o comportamento de limitação diferem entre os idiomas. O código que depende do comportamento de repetição legado pode se comportar de forma diferente quando movido entre SDKs.

Disponível em: Java, Python, Ruby, PHP, C++, CLI

Não disponível em: .NET, Go, Kotlin, Rust, Swift, JavaScript

O modo legado existe para compatibilidade com versões anteriores. Se você usa atualmente o modo legado, mude para o modo padrão.

Tentar novamente as configurações

As configurações a seguir controlam o comportamento de repetição. Você pode defini-las por meio de variáveis de ambiente, do arquivo de configuração compartilhado (~/.aws/config) ou da configuração do cliente no código.

Um valor máximo de tentativas 3 significa que o SDK faz uma solicitação inicial e até duas novas tentativas. Defina o máximo de tentativas 1 para desativar totalmente as novas tentativas.

Precedência de configuração

Quando você especifica a mesma configuração em vários lugares, o SDK resolve o valor usando a seguinte precedência, da maior para a menor:

Isso segue a precedência de configuração padrão do AWS SDK. Um valor definido em um nível superior sempre substitui um valor definido em um nível inferior. Por exemplo, se você definir AWS_RETRY_MODE=adaptive como uma variável de ambiente e retry_mode=standard em~/.aws/config, o SDK usará o modo adaptativo.

Language-specific configuração

As configurações entre SDKs descritas nesta página (retry_modeemax_attempts) funcionam em todos os SDKs. No entanto, a API para configurar novas tentativas no código varia de acordo com o idioma. Consulte o guia do desenvolvedor do seu SDK para obter opções de configuração específicas do idioma, como estratégias de recuo personalizadas, erros adicionais que podem ser repetidos e ajuste de cota de novas tentativas.

Como funcionam as novas tentativas

Esta seção descreve como AWS os SDKs lidam com solicitações falhadas: quais erros acionam novas tentativas, quanto tempo o SDK espera entre as tentativas e quando ele para de tentar novamente.

O que acontece quando uma solicitação falha

Quando você faz uma chamada de API por meio de um AWS SDK, o SDK segue esta sequência:

O SDK repete esse ciclo até que a solicitação seja bem-sucedida, o número máximo de tentativas seja atingido, a cota de novas tentativas seja esgotada ou ocorra um erro que não pode ser repetido. Todo o processo é automático. Seu aplicativo vê uma resposta bem-sucedida ou um erro final.

Quais erros são repetidos

O SDK classifica cada solicitação com falha em uma das três categorias: transitória, limitada ou não repetitiva. Essa classificação determina se o SDK tenta novamente a solicitação e quanto tempo espera antes de tentar novamente.

A classificação é baseada no código de erro e no código de status HTTP na resposta do serviço. Por exemplo, um HTTP 400 com o código de erro RequestTimeout é classificado como transitório e repetido. Um HTTP 400 com ValidationException é classificado como não passível de repetição e retornado imediatamente.

Classificação de erros

Os erros transitórios são repetidos com um pequeno atraso básico (50 ms):

Os erros de limitação são repetidos com um atraso base maior (1.000 ms):

Non-retryable erros (comoAccessDeniedException,ValidationException,ResourceNotFoundException) retornam ao seu código imediatamente.

Erros de limitação significam que o serviço rejeitou ativamente sua solicitação devido aos limites de taxa, então o SDK espera mais tempo antes de tentar novamente dar tempo ao serviço para recuperar a capacidade. Veja Quanto tempo o SDK espera os atrasos específicos.

Quanto tempo o SDK espera

O SDK usa recuo exponencial com instabilidade total. Em média, cada nova tentativa espera mais do que a última, com aleatoriedade para distribuir as solicitações de vários clientes.

Atrasos básicos por tipo de erro

O atraso básico depende se o erro é transitório ou limitado:

Fórmula de recuo

O SDK calcula cada atraso de nova tentativa usando esta fórmula:

delay = random(0, 1) × min(20,000 ms, base_delay × 2^retry)

Em que:

O limite máximo de recuo é de 20 segundos. Nenhum atraso individual excede 20 segundos, independentemente de quantas tentativas tenham ocorrido.

Exemplos trabalhados

Exemplo 1: erro transitório, máximo de 3 tentativas

A latência total adicionada é em média de cerca de 75 ms em ambas as tentativas.

Exemplo 2: erro de limitação, 3 tentativas máximas

A latência total adicionada é em média de cerca de 1.500 ms em ambas as tentativas.

Exemplo 3: Erro transitório, atingindo o limite de recuo

Com um atraso básico de 50 ms, o atraso computado antes do limite seria:

O limite entra em vigor na 10ª tentativa (11ª tentativa) para erros transitórios. Para erros de limitação com uma base de 1.000 ms, o limite entra em vigor na 6ª tentativa.

Por que o nervosismo é importante

O multiplicador aleatório é chamado de variação total. Sem isso, todos os clientes que detectassem um erro ao mesmo tempo tentariam novamente ao mesmo tempo, criando uma explosão de tráfego de novas tentativas (o problema do “rebanho estrondoso”). O jitter total distribui as novas tentativas uniformemente por toda a janela de recuo, para que o serviço receba um fluxo constante de solicitações em vez de picos sincronizados.

Por exemplo, suponha que 1.000 clientes recebam um 503 ao mesmo tempo. O jitter total distribui suas primeiras tentativas uniformemente em uma janela de 50 ms, em vez de ter todas as 1.000 novas tentativas em exatamente 50 ms.

Server-directed tempo de repetição

Alguns Serviços da AWS incluem um x-amz-retry-after cabeçalho nas respostas de erro. O valor do cabeçalho é um atraso em milissegundos. Quando esse cabeçalho está presente, o SDK usa o atraso especificado pelo servidor, limitado a um mínimo do atraso de recuo calculado e ao máximo do atraso de recuo calculado mais 5.000 ms. Como o próprio recuo computado é limitado a 20 segundos, o atraso máximo efetivo direcionado ao servidor é de 25 segundos. O SDK não aplica instabilidade a esse valor, pois espera-se que o serviço o altere. Isso permite que o serviço se comunique exatamente quando espera ter capacidade disponível.

Cota de repetição (bucket de tokens)

O SDK mantém um orçamento interno de tokens que monitora a proporção entre solicitações bem-sucedidas e falhas. Quando as falhas são generalizadas, o orçamento se esgota e o SDK retorna os erros diretamente. Seu aplicativo falha rapidamente em vez de esperar por novas tentativas que provavelmente não serão bem-sucedidas. Isso também reduz o tráfego de novas tentativas, ajudando as interrupções no serviço a serem resolvidas mais rapidamente.

Como funciona a cota de novas tentativas

O orçamento do token começa cheio. Cada tentativa de nova tentativa deduz os tokens. Quando uma nova tentativa é bem-sucedida, o SDK restaura os tokens consumidos por essa nova tentativa. Quando uma solicitação é bem-sucedida na primeira tentativa (sem necessidade de novas tentativas), o SDK restaura 1 token. Quando o orçamento chega a zero, o SDK para de tentar novamente e retorna os erros diretamente ao seu código.

O custo mais alto das novas tentativas transitórias reflete seu padrão de falha diferente. Erros transitórios como 500s e falhas de conexão geralmente indicam um problema em todo o serviço. Nessas situações, é improvável que a repetição contínua tenha sucesso. Ele adiciona latência às suas chamadas, consome os recursos do cliente e pode atrasar a recuperação de todos. Erros de limitação indicam que o serviço precisa de mais tempo antes que a solicitação seja bem-sucedida. O SDK espera mais tempo entre as novas tentativas para aumentar a probabilidade de sucesso.

Quando o bloco de cotas tenta novamente?

A cota de novas tentativas rastreia os tokens o tempo todo, mas só bloqueia novas tentativas quando o orçamento está esgotado. Durante a operação normal, quase todas as solicitações são bem-sucedidas e o orçamento permanece cheio. A cota não tem efeito observável nas novas tentativas.

Uma nova tentativa bem-sucedida restaura somente seu próprio custo de token (14 ou 5 tokens), não o custo de novas tentativas anteriores que falharam na mesma solicitação. Por exemplo, se a primeira tentativa falhar e a segunda for bem-sucedida, o orçamento perderá 14 tokens líquidos. O orçamento diminui mais rapidamente quando as novas tentativas esgotam todas as tentativas sem sucesso, mas também diminui gradualmente quando as solicitações precisam de várias tentativas antes de serem bem-sucedidas.

Com o padrão de 3 tentativas máximas, a cota começa a diminuir quando mais de aproximadamente 22% das solicitações resultam em falhas transitórias sustentadas ou mais de aproximadamente 32% em erros de limitação. Abaixo dessas taxas, as solicitações bem-sucedidas reabastecem o orçamento mais rapidamente do que as tentativas fracassadas o esgotam.

O saldo inicial do orçamento de 500 tokens fornece um buffer que absorve pequenos períodos de falhas. Um breve pico de erros, mesmo um grave, não bloqueia novas tentativas, a menos que persista por tempo suficiente para drenar o buffer.

Implicações práticas

Service-specific comportamento

DynamoDB

Os clientes do DynamoDB usam padrões ajustados otimizados para o perfil de baixa latência do DynamoDB:

Esses padrões se aplicam aos streams do Amazon DynamoDB e do DynamoDB.

Long-polling operações

Certas AWS operações usam pesquisas longas. Eles podem manter uma conexão aberta aguardando a chegada do trabalho. Essas operações recebem tratamento especial de repetição:

Comportamento especial: quando a cota de novas tentativas se esgota e as novas tentativas são bloqueadas (etapa 7O que acontece quando uma solicitação falha), o SDK ainda aplica um atraso antes de retornar o erro ao seu código.

Isso é importante porque as operações de sondagem longa geralmente são chamadas em um ciclo restrito. Seu código chamaReceiveMessage, processa qualquer mensagem e liga imediatamente ReceiveMessage novamente. Sem o recuo forçado, um orçamento de token esgotado faria com que o SDK retornasse erros sem demora. Seu ciclo de pesquisa enviaria imediatamente a próxima solicitação, aumentando o uso da CPU do cliente e gerando tráfego adicional. O atraso forçado do recuo interrompe esse ciclo, mantendo o uso de recursos do cliente e a taxa de pesquisa gerenciáveis durante falhas.

Apoio de AWS SDKs e ferramentas

A tabela a seguir lista a disponibilidade do comportamento de repetição atualizado em cada SDK. Para SDK-specific obter detalhes, incluindo versão mínima, padrões antes e depois e exemplos de código, consulte o problema de rastreamento. GitHub