Conceito e mecanismo
A operação de uma API precisa de distinguir tentativas técnicas de operações de negócio. Um cliente pode repetir um pedido várias vezes até obter resposta, aumentando tráfego mesmo que a maioria das operações termine. Num exercício original, 1200 operações geram 180 tentativas adicionais: são 1380 tentativas e 15% de carga adicional face a uma tentativa por operação.
Não uses a taxa de respostas isoladamente para afirmar quantas operações foram concluídas. Perante 429, respeita a orientação de espera quando fornecida e usa uma política limitada compatível com o contrato. Uma repetição ilimitada e sincronizada pode agravar a sobrecarga que pretende resolver.
Aplicação guiada
Num incidente fictício, o gateway regista timeout mas o worker continua a processar. Liga os registos por identificador de operação e contexto de tracing, sem colocar dados pessoais ou segredos nos campos de correlação. Determina onde o prazo terminou e se houve efeito no negócio antes de reenviar.
Para evolução, mantém inventário de consumidores, testes de compatibilidade, documentação e responsáveis. Deprecation informa descontinuação recomendada sem mudar por si só o comportamento do recurso; Sunset comunica quando se espera que deixe de responder.
Nenhum header substitui coordenação de migração. Uma remoção só deve seguir o plano revisto, com alternativas utilizáveis e evidência de transição dos consumidores relevantes.
1200 operações mais 180 retries resultam em 1380 tentativas; a contagem de tentativas não é a contagem de operações concluídas.
Armadilhas comuns
Retry ilimitado como resiliência; trace como autorização; deprecation como desligamento;200 como único indicador de sucesso.
Tópicos relacionados: Recursos e contratos de API · Pedidos e resultados · Concorrência e repetição
Relaciona telemetria técnica com conclusão de negócio e compatibilidade.
Referências
- Trace Context · Trace Context Recommendation consulted 2026-09-30
- RFC6585 Additional HTTP Status Codes · RFC6585 April 2012
- RFC9110 HTTP Semantics · RFC9110 June 2022
- RFC9745 The Deprecation HTTP Response Header Field · RFC9745 March 2025
- RFC8594 The Sunset HTTP Header Field · RFC8594 May 2019