Verificar formato da chave de idempotência

Ela verifica se a chave não está vazia, se é longa o suficiente para ser única na prática, se permanece dentro de um comprimento máximo razoável e se cada caractere é seguro para URL, de modo que a chave sobreviva a cabeçalhos, logs e query strings sem surpresas de codificação. Você envia uma string e recebe um indicador valid claro, o comprimento medido e uma lista de problemas concretos quando algo está errado.

Por que chaves de idempotência precisam de verificação de formato

Chaves de idempotência existem para que uma requisição repetida — um pagamento enviado duas vezes, um pedido criado após um timeout — seja processada uma única vez. Mas a segurança que prometem depende de a própria chave estar bem formada. Uma chave curta demais colide com a chave de outro cliente e deduplica silenciosamente duas operações diferentes em uma só. Uma chave com caracteres fora do alfabeto seguro para URL é mutilada em algum ponto entre o seu cliente, um proxy, o pipeline de logs e o servidor, de modo que a repetição chega com uma string diferente da original e é cobrada duas vezes. Uma chave vazia é rejeitada de imediato pela maioria das APIs, muitas vezes com um erro genérico que leva uma tarde inteira para rastrear. Passar a chave por esta verificação de formato de chave de idempotência na borda do seu sistema captura os três modos de falha em tempo de desenvolvimento, numa suíte de testes ou numa validação prévia dentro do seu próprio serviço, em vez de num relatório de reconciliação semanas depois.

O que exatamente é validado

A verificação aplica as orientações de formato que processadores de pagamento e middlewares de deduplicação documentam com mais frequência. Primeiro, a chave deve ser uma string não vazia; uma chave vazia é um erro, não um aviso, porque nenhum servidor a aceitará. Segundo, o comprimento: por padrão a chave deve ter pelo menos 16 caracteres, o piso abaixo do qual a unicidade deixa de ser plausível, e no máximo 255 caracteres, o teto que a maioria dos armazenamentos aceita — ambos os limites são configuráveis por chamada. Terceiro, o alfabeto: cada caractere deve pertencer ao conjunto não reservado da RFC 3986 — letras, dígitos, hífen, ponto, sublinhado e til. Esses caracteres atravessam cabeçalhos HTTP, segmentos de URL e transportadores de logs sem codificação, que é exatamente por onde as chaves de idempotência viajam. Quando um caractere falha, a resposta lista cada caractere infrator distinto para que você veja se alguém embutiu um espaço, uma barra ou um emoji, e o array issues nomeia o problema de forma legível por máquina: too_short, too_long ou unsafe_characters.

Onde a verificação se encaixa na sua stack

A maioria das equipes a integra em dois lugares. O primeiro é o cliente que gera as chaves: logo depois de montar uma chave a partir de um UUID, um timestamp e um id de usuário, valide-a uma vez e registre um aviso se ela falhar, para que um bug do gerador apareça em staging em vez de produção. O segundo é o teste de contrato: envie um lote de chaves de cada integração que você mantém pelo endpoint no CI, de modo que uma atualização de biblioteca que mude o comportamento de codificação quebre o build. O endpoint é determinístico e sem estado — nada é armazenado, nenhuma lista de chaves já vistas é consultada e a mesma entrada sempre produz a mesma saída —, o que significa que é seguro chamá-lo com chaves reais e barato o bastante, a US$ 0,002 por requisição, para rodar em cada deploy. A mesma validação também roda grátis no seu navegador nesta página, então um desenvolvedor pode colar uma chave suspeita durante um incidente e obter a mesma resposta que a API daria.