Resumo

  • O rascunho HTTPAPI sobre Idempotency-Key, hoje expirado e arquivado, coloca o ciclo de vida da chave e a política de expiração no contrato do recurso. A documentação de Stripe e os exemplos de AWS mostram limites próprios, não um prazo universal.
  • A memória para reconhecer uma repetição não deve ser confundida com autoridade para produzir outro efeito. Fora da janela, uma operação antiga de resultado desconhecido precisa de consulta, conciliação ou espera controlada; a falta da chave não prova que nada aconteceu.

O trabalho pode ter terminado sem que a resposta tenha chegado. Uma conexão cai, o cliente registra timeout e o servidor continua. A aplicação pode já ter criado um recurso ou enviado uma instrução adiante. O solicitante conhece apenas a ausência de confirmação, não a ausência de efeito.

A idempotência serve para recuperar parte dessa incerteza. Um identificador permite ao serviço reconhecer uma tentativa posterior como repetição da anterior. Dentro do contrato, ele pode devolver o resultado já produzido ou informar que a operação ainda está em curso, em vez de produzir uma segunda consequência.

Mas imagine um executor que fica parado por dias e depois reenvia a mesma carga com a mesma chave. Se a entrada ainda existe, o serviço pode reconhecê-la. Se foi eliminada conforme a política de retenção, a camada de deduplicação talvez enxergue um primeiro pedido. O cliente não necessariamente mudou de intenção. A memória de outra parte mudou de estado.

É aí que uma promessa genérica de «repetição segura» se torna insuficiente. A garantia depende de escopo, comparação de parâmetros, armazenamento e tempo. Uma sequência aleatória ajuda a identificar a tentativa; não demonstra que a ação anterior jamais ocorreu nem concede autoridade para repeti-la depois que a identificação foi esquecida.

Publicado em 15 de outubro de 2025, draft-ietf-httpapi-idempotency-key-header-07 descreve uma proposta de campo estruturado com valor de string, unicidade de chave, impressão digital opcional da carga e tratamento distinto de duplicatas concluídas e concorrentes. A responsabilidade pelo ciclo de vida e pela publicação da política de expiração pertence ao recurso.

A revisão 07 expirou em 18 de abril de 2026. No corte desta pesquisa, Datatracker a apresenta como Internet-Draft do grupo HTTPAPI expirado e arquivado. Não é rascunho ativo, RFC nem padrão aprovado. Ser documento de grupo de trabalho não equivale a consenso institucional. O artigo usa a proposta para analisar um problema, sem transformá-la em obrigação geral de HTTP.

Timeout não é um estado terminal

O RFC 9110 define a idempotência de um método pelo efeito pretendido de chamadas repetidas. Isso não obriga respostas ou logs idênticos nem garante execução exatamente uma vez por toda uma cadeia. Um serviço pode criar um contrato idempotente para uma operação POST ou PATCH, mas a presença de um cabeçalho não torna qualquer mutação globalmente única.

O rascunho lembra que um cliente genérico não pode pressupor que um servidor arbitrário respeitará a chave. Precisa conhecer a especificação do recurso: em que escopo ela é única, quais partes da carga definem equivalência, quanto dura o reconhecimento e o que ocorre durante o processamento.

Uma repetição depois da conclusão pode recuperar o resultado anterior, inclusive uma falha. Uma repetição antes da conclusão pode receber conflito. A mesma chave com outra carga é um problema diferente. Esses casos não devem ser reunidos num único procedimento de gerar token novo e tentar novamente. O novo token pode iniciar uma ação adicional sem esclarecer a primeira.

A comparação por impressão digital também exige uma escolha semântica. Calcular um hash de tudo ou selecionar campos define quais diferenças contam. Um campo recém-importante omitido pode fazer intenções distintas parecerem iguais. Uma normalização inofensiva pode fazer a mesma intenção parecer diferente. Entropia não corrige uma definição inadequada de equivalência.

O prazo faz parte da promessa

Reter cada token, resposta e carga indefinidamente tem custos de armazenamento, privacidade e operação. Recursos têm vidas distintas, e atrasos plausíveis variam. A questão não é proibir a eliminação. É explicar ao cliente o que deixa de estar garantido depois dela e como decidir sem produzir um efeito indevido.

Stripe oferece um caso concreto em sua documentação atual. Guarda o primeiro status e corpo para a chave quando a execução do endpoint começa, incluindo resultados de erro. Falha de validação ou conflito antes do início não gera esse resultado guardado. A documentação permite remover chaves quando têm pelo menos 24 horas e afirma que o uso de uma chave já eliminada gera uma nova requisição.

Isso não é garantia de que toda chave some exatamente em 24 horas, regra para outros serviços ou relato de cobrança duplicada. É uma política específica que o cliente deve considerar. Uma fila capaz de voltar dias depois não mantém a antiga segurança só por conservar a sequência original.

AWS descreve em Builders Library uma situação diferente: uma repetição tardia chega depois que outro ator apagou o recurso inicialmente criado. No exemplo EC2, o contrato preserva uma resposta semanticamente equivalente em vez de recriar o recurso. O texto trata de retenção ligada à vida do recurso mais um intervalo para chegadas tardias e ressalta que os requisitos variam entre serviços e recursos.

Não se deve extrair dos casos um TTL comum. Uma repetição breve de SDK, um dispositivo desconectado, uma recuperação de desastre e uma ação manual têm horizontes diferentes. O confronto desses horizontes com a memória do serviço identifica o problema. Mais backoff pode distribuir carga, mas não restaurar o conhecimento eliminado.

Separar token, operação, efeito e intenção nova

A chave de deduplicação identifica uma tentativa dentro de um escopo. A operação de negócio identifica a instrução autorizada. O efeito identifica o que foi criado, alterado ou transmitido. Uma intenção nova pode autorizar uma consequência adicional. Essas identidades devem estar relacionadas, sem que uma substitua todas as outras.

Trocar a chave não prova que a intenção mudou. Reutilizar uma chave depois da limpeza não prova fracasso da operação antiga. A exclusão de um recurso não significa que ele jamais existiu. Ao mesmo tempo, parâmetros iguais podem representar uma segunda ação legítima. A autoridade não pode ser deduzida apenas da igualdade ou diferença de bytes.

Um registro compacto da operação pode durar além da memória ordinária de resposta. Pode reunir escopo do solicitante, instrução autorizada, compromisso sobre parâmetros, aceitação, estado terminal, referência ao efeito e caminho de conciliação. Não precisa copiar para sempre cargas sensíveis e respostas completas. Acesso, finalidade e retenção continuam sujeitos a limites.

Esse registro é uma recomendação de governança, não um campo obrigatório inventado para Idempotency-Key. Diferentes arquiteturas podem alcançar o mesmo resultado. O princípio é preservar uma maneira defensável de decidir se uma instrução antiga e incerta ainda pode agir, mesmo quando o cache comum já terminou.

Definir a resposta fora da janela

A política deve informar o início da contagem, o escopo do chamador e da operação, a retenção de erros concluídos e a situação de tarefas em andamento. Também deve descrever a chegada tardia: rejeição, consulta, conciliação ou espera examinável. Um prazo isolado não explica recuperação após perda de resposta.

Depois da janela, a entrega ambígua não deve se converter silenciosamente em execução nova. O cliente pode suspender envio automático, consultar a operação ou o recurso conhecido e encaminhar a incerteza a quem pode decidir. Para outro efeito, precisa haver intenção nova explícita, separável da tentativa antiga de recuperação.

Um fornecedor pode publicar que chave reutilizada após limpeza será tratada como nova requisição. Isso define comportamento técnico, não cria uma decisão de negócio do solicitante. O fluxo do cliente precisa parar de apresentar o envio tardio como se ainda estivesse coberto pela garantia anterior.

Suporte humano também entra nessa fronteira. Clicar em «tentar novamente» três dias depois não necessariamente usa o mesmo contrato que um SDK segundos após a falha. Gerar outra chave para fugir de conflito pode fechar o chamado enquanto abre uma segunda operação. A interface deve mostrar qual decisão está sendo tomada.

Conferir a memória contra a consequência

Registrar o token sem criar o recurso pode produzir falsa conclusão. Criar o recurso sem registrar o token pode permitir repetição. A descrição de AWS enfatiza coordenar o registro e as mutações pertinentes num processo atômico, de tudo ou nada.

Uma transação local, porém, pode não cobrir o trabalho de outro sistema. O primeiro confirma sua linha, o segundo executa uma instrução e a confirmação se perde. O estado terminal deve se apoiar na fonte autoritativa de cada efeito. Conclusão na primeira base não comprova conclusão de toda a cadeia.

Testes devem incluir entrega após o prazo, repetição depois de excluir o recurso, parâmetros diferentes, mudança de escopo do solicitante e conclusão parcial em outro serviço. O resultado esperado não é só um status escolhido. É evitar uma segunda consequência sem autorização e descrever honestamente o estado ainda desconhecido.

Um backup pode restaurar a instrução antiga; um equipamento pode reconectar tarde; um export de suporte pode devolver trabalho já conciliado. Esses são caminhos normais da recuperação. Tratá-los como detalhe raro deixa a política de armazenamento determinar autoridade por acidente.

Fontes

  1. Registro do rascunho expirado
  2. Histórico do rascunho
  3. Revisão 07 em HTML
  4. Revisão 07 em texto
  5. XML da revisão 07
  6. Mandato de HTTPAPI
  7. Documentos de HTTPAPI
  8. Repositório oficial
  9. Questões do rascunho
  10. RFC 9110: semântica HTTP
  11. RFC 9457: detalhes de problemas em API
  12. RFC 8941: campos estruturados HTTP
  13. RFC 9562: identificadores UUID
  14. RFC 9111: cache HTTP
  15. Stripe: requisições idempotentes
  16. Stripe: erros de baixo nível
  17. AWS: repetição segura com API idempotentes
  18. AWS: timeouts, tentativas e backoff
  19. Lu Heng: especificação inicial mínima e decisão local
  20. Lu Heng: o espelho da política