APRENDER. PRATICAR. EVOLUIR.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ência: Trace Context · HTTP semantics RFC9110; OpenAPI3.2.1; selected primary standards and provider contracts consulted2026-09-30