Leonardo Peron5 min de leitura
A integração parou às três da manhã. Ninguém percebeu até as nove, quando o faturamento reclamou que os pedidos da noite não estavam lá. A rede estava boa, o fornecedor estava no ar, o código não mudou. O que aconteceu foi um token expirando, um certificado chegando à data, ou uma senha rotacionada no painel do fornecedor por alguém que não sabia que aquilo alimentava uma rotina.
Três problemas diferentes com o mesmo sintoma
Vale separá-los antes de escrever qualquer linha: a solução de um não cobre os outros.
Token de curta duração. Vale minutos ou horas e é renovável por chamada. É o único dos três com solução inteiramente técnica.
Segredo de longa duração. Chave de API, senha, segredo de cliente. Não expira sozinho: muda quando uma pessoa decide. A defesa não é código, é aviso — a integração precisa aparecer na lista de quem depende daquela credencial, para que a rotação seja combinada em vez de descoberta.
Certificado. Autenticação mútua, assinatura de requisição, o que bancos e o Pix exigem. Tem data marcada, e a renovação é procedimento com prazo, não chamada. Times que constroem uma renovação de token impecável continuam sendo derrubados por certificado vencido, porque trataram os dois como o mesmo problema.
Renovação preguiçosa é melhor que agendada
A renovação agendada — "todo dia às quatro" — assume três coisas: que o processo está vivo naquele horário, que a renovação deu certo, e que nada invalidou a credencial no meio do caminho. As três podem estar erradas em silêncio, e a descoberta acontece na primeira requisição seguinte, quando já não dá para reagir.
A renovação preguiçosa inverte a lógica: toda chamada pede a credencial a um componente único, que renova se ela não existir, tiver expirado ou estiver perto de expirar. A renovação acontece porque alguém precisa dela, exatamente quando importa.
Dois refinamentos separam funcionar de quase funcionar.
Renove antes do vencimento, com margem. Um token que expira em trinta segundos não sobrevive à requisição que está começando, e os relógios dos dois lados não são o mesmo. Tratar como expirado o que vence em breve elimina uma classe inteira de falha intermitente.
Trate o 401 assim mesmo. A margem reduz, não elimina: o outro lado pode revogar a qualquer momento. A segunda linha é receber 401, renovar uma vez e repetir a requisição — uma vez, com marcação, senão vira laço.
Uma renovação por vez
O defeito a seguir só aparece com concorrência e derruba a integração inteira. Vinte chamadas em paralelo descobrem, no mesmo instante, que o token expirou. Vinte renovações saem juntas. Em fornecedor que invalida o token anterior a cada emissão, os vinte se derrubam entre si: cada chamada usa um token que a emissão seguinte já matou. O sintoma é uma sequência de 401 que parece problema do fornecedor e é de desenho.
A regra é uma renovação de cada vez. Quem chega no meio espera e usa o resultado de quem já estava renovando.
401 não é falha de negócio
O engano clássico: a integração recebe a recusa, marca o evento como erro e o manda para a fila de falhas com a mensagem que o fornecedor devolveu. Em minutos a fila enche de itens cujo único defeito foi atravessar uma janela de cinco minutos, e depois alguém reprocessa aquilo em bloco sem saber que não havia nada errado ali.
A leitura correta é outra: 401 significa que o pedido não chegou a ser avaliado. O fato não falhou, ele não foi tentado. Pertence à retentativa depois da renovação, não ao arquivo de dado defeituoso.
Duas ressalvas. Um 403 depois de renovação bem-sucedida é outra coisa — permissão ou escopo faltando —, e repetir não resolve. E há fornecedor que devolve sucesso com o erro de autenticação no corpo, o que desmancha a distinção inteira: vale conferir como o seu responde.
O que registrar quando a renovação falha
A falha da renovação é um evento diferente da falha da requisição e merece linha própria: qual credencial e qual endereço foram usados — o identificador do cliente, nunca o segredo —, a resposta literal do fornecedor e quando foi a última renovação bem-sucedida.
A resposta literal importa porque motivos parecidos apontam para causas distintas: segredo errado e concessão revogada pedem ações diferentes. E o alarme fica na renovação, não só nas requisições — é ele que chega antes da enxurrada, com os minutos que dão para agir.
Nunca registre o token. Ele é credencial válida enquanto durar, e log é o lugar menos protegido do sistema.
O prazo que não está na agenda de ninguém
Certificado e segredo longo precisam de uma data em algum lugar que avise com semanas de antecedência. E o procedimento de troca precisa estar escrito: o dia do vencimento é o pior momento para descobrir que o certificado novo tem de ser cadastrado no painel do fornecedor por uma pessoa cujo acesso ninguém tem mais.
Onde o fornecedor permite duas credenciais válidas ao mesmo tempo, a troca é somar a nova, apontar para ela e só então remover a antiga. Trocar no lugar transforma qualquer erro em parada.
O teste que confirma
Invalide a credencial de propósito com um lote rodando: revogue no painel do fornecedor, ou force o vencimento no seu próprio cache para um instante passado.
O comportamento certo é uma renovação, uma pausa curta e o lote terminando inteiro — nada na fila de erro, nada marcado como defeito de dado.
Depois repita com vinte chamadas simultâneas e conte quantas renovações saíram. Se saíram vinte, o controle de renovação única ainda não existe — e ele só se manifesta no dia de pico.