Retries sem efeitos duplicados: desenhar idempotência como contrato de API

Semântica idempotente e execução única não são a mesma promessa

RFC 9110 define PUT, DELETE e métodos seguros como idempotentes em termos do efeito pretendido pelo cliente. Logs, métricas e outras consequências secundárias podem repetir. POST e PATCH não são idempotentes por definição, mas uma aplicação pode oferecer uma operação tolerante a retry por contrato.

O Internet-Draft de Idempotency-Key descreve boas ideias — unicidade, fingerprint, responsabilidades e erros — mas continua work in progress expirado. Documente o comportamento na OpenAPI e não afirme compatibilidade com um standard inexistente.

Especificar todos os estados que o cliente pode observar

O happy path é a parte fácil. Documente resposta quando o primeiro pedido está em progresso, quando concluiu, quando falhou antes do efeito, quando o efeito é incerto, quando a chave mudou de payload e quando expirou. Use Problem Details para erros legíveis por máquina sem expor dados sensíveis.

Testar nos pontos onde a rede corta a narrativa

Injete falha antes de reservar, depois de reservar, antes do commit, depois do commit e antes da resposta. Repita com dois pedidos simultâneos e com duas instâncias do servidor. Conte efeitos no sistema de registo, não apenas respostas HTTP.

Escolha retenção a partir da maior janela de retry, latência assíncrona, reconciliação e risco de operação duplicada. Para pagamentos ou efeitos irreversíveis, prefira consulta de estado e referência durável a adivinhar que falhou.

• Não usar a chave como segredo nem permitir que atravesse tenants.
• Aplicar rate limit sem apagar o registo de deduplicação.
• Guardar hash/fingerprint canónico sem conservar payload sensível desnecessário.
• Monitorizar replays, conflitos, operações presas, expirações e reconciliações.