Timeouts, retries e backoff com jitter

Objetivo

Tornar um cliente resiliente a falhas transitórias sem agravar uma indisponibilidade nem duplicar trabalho.

Pré-requisitos

Saber quais operações são idempotentes (ou protegidas por chaves de idempotência) e o que o servidor sinaliza em caso de sobrecarga (429 ou 503 com Retry-After).

Passos

1. Defina um timeout de conexão e um timeout de leitura em toda chamada remota; escolha-os a partir do prazo do próprio chamador, não do pior caso já observado.
2. Faça retry apenas em resultados transitórios: erros de conexão, timeouts, 429, 503 e 502/504 vindos de intermediários. Nunca repita em erros de validação 4xx.
3. Repita apenas operações idempotentes ou operações com chave de idempotência; um POST simples só é repetido se o servidor documentar comportamento idempotente.
4. Espace os retries de forma exponencial (base × 2^tentativa) com jitter aleatório, como recomenda a análise da AWS citada, e limite tanto o atraso quanto o número de tentativas.
5. Respeite Retry-After quando o servidor o enviar; ele tem prioridade sobre o atraso calculado.
6. Adicione um circuit breaker ou um orçamento, para que uma dependência com falha não consuma toda a capacidade do cliente.

Resultado esperado

Os clientes se recuperam sozinhos de interrupções curtas, a carga sobre um servidor em recuperação aumenta de forma gradual e nenhuma operação é executada duas vezes por acidente.

Limites e base de verificação

Retries aumentam a latência; em caminhos interativos pode ser preferível falhar rapidamente. Os parâmetros de backoff precisam ser ajustados para cada dependência. As recomendações seguem as fontes citadas e a prática do cliente de exemplo desta wiki.

Cabeçalhos informativos de limite de taxa

Alguns servidores anunciam seus limites antes de qualquer 429. Um rascunho do IETF (draft-ietf-httpapi-ratelimit-headers) define um campo RateLimit, que informa a cota restante e os segundos até ela ser reiniciada, e um campo RateLimit-Policy, que descreve a política; outros servidores enviam cabeçalhos próprios do fornecedor com o mesmo significado. Quando esses campos estiverem presentes, leia-os e reduza o ritmo antes de a cota chegar a zero, e não depois; trate-os como indicações que podem estar ausentes ou mudar de formato, e mantenha o backoff dos passos 4 e 5 como alternativa de segurança. Nunca deixe um cabeçalho informativo elevar a taxa de requisições acima do que o orçamento do próprio chamador permite.