Automação resiliente: como criar rotinas que não quebram no primeiro erro idiota

automação resiliente não é nome bonito para vender consultoria. É o que separa uma rotina útil de um castelo de cartas com Wi-Fi. Toda pessoa que automatiza alguma coisa passa pela fase da empolgação: cria um script, pluga uma API, agenda um cron e pensa que agora a vida ficou resolvida. Aí vem a segunda-feira, a API responde diferente, o token expira, o arquivo chega com nome estranho, e a automação que deveria economizar tempo vira um segundo emprego.

Eu já fiz isso mais vezes do que gostaria de admitir. A versão honesta da história é simples: automação sem projeto de falha é só otimismo executável. Funciona quando o mundo colabora. O problema é que o mundo raramente colabora, especialmente quando tem rede, credenciais, WordPress, planilhas, IA, webhooks e uma pitada de sono acumulado no meio.

Neste guia, vou mostrar um método prático para construir automação resiliente em rotinas pequenas e médias: jobs de publicação, integrações com APIs, coleta de dados, backups, alertas e tarefas recorrentes. A ideia não é criar uma catedral de engenharia para mandar um e-mail. É criar o mínimo de estrutura para o robô fazer o trabalho certo, falhar com dignidade e deixar pistas decentes quando alguma coisa der errado.

O problema real: automações quebram em lugares sem glamour

A maioria das falhas não acontece no algoritmo sofisticado. Acontece no detalhe besta: uma variável de ambiente vazia, uma resposta HTTP 429, um campo JSON que virou nulo, um timezone que muda a interpretação da data, um arquivo que não terminou de baixar, um endpoint que devolve HTML de erro onde você esperava JSON. É nesse pântano que mora a engenharia de verdade.

Quando alguém diz “meu script parou do nada”, quase nunca foi do nada. Só não havia telemetria, validação ou registro suficiente para enxergar a causa. O script era uma sequência de comandos felizes, todos assumindo que o comando anterior tinha dado certo. Isso é fofo. Também é uma forma cara de aprender humildade.

A pergunta que resolve metade do caos é: o que precisa ser verdade para esta etapa continuar? Se a resposta não está validada no código, você está rezando. Rezar pode até acalmar, mas não transforma resposta quebrada em dado confiável.

Princípio 1: defina o contrato de entrada antes da primeira linha útil

Toda automação tem entradas. Pode ser uma API, um arquivo, uma tabela, uma mensagem, uma pasta ou um comando agendado. Antes de processar qualquer coisa, descreva o contrato mínimo: quais campos precisam existir, quais formatos são aceitos, quais valores são proibidos e quais limites fazem sentido.

Um job de publicação, por exemplo, não deveria aceitar “qualquer título” e “qualquer conteúdo”. Ele deveria saber que o título não pode estar vazio, que o conteúdo precisa ter tamanho mínimo, que a categoria precisa existir no WordPress, que tags precisam ser IDs inteiros, que imagem destacada precisa ter sido enviada e que status final precisa ser conferido depois da publicação.

function assertPostPayload(post) {
  if (!post.title || post.title.length < 20) throw new Error('titulo fraco ou vazio');
  if (!post.content || post.content.split(/\s+/).length < 1200) throw new Error('conteudo curto demais');
  if (!Number.isInteger(post.categoryId)) throw new Error('categoria invalida');
  if (!Number.isInteger(post.featuredMediaId)) throw new Error('featured media ausente');
  return true;
}

Repare que isso não é burocracia. É uma cerca baixa para impedir que lixo entre no fluxo. Sem essa cerca, a sujeira só aparece no fim, quando já foi enviada para uma API externa, gravada em banco, publicada em produção ou espalhada por três sistemas que agora discordam entre si.

Princípio 2: trate APIs como colegas instáveis, não como divindades

APIs falham. APIs mudam. APIs ficam lentas. APIs devolvem mensagens lindas em documentação e respostas esquisitas às 2h17. A automação resiliente parte do pressuposto de que qualquer chamada externa pode dar errado e que o erro precisa ser classificado.

Nem todo erro merece a mesma reação. Um 401 pede renovação de credencial ou intervenção humana. Um 404 pode indicar dado inexistente. Um 409 talvez seja conflito recuperável. Um 429 pede espera. Um 500 merece retry com limite. Um timeout precisa ser registrado com contexto. Jogar tudo no mesmo “deu ruim” é confortável, mas inútil.

http_code=$(curl -sS -o resposta.json -w "%{http_code}" "$URL")
case "$http_code" in
  200|201) echo "ok" ;;
  429) echo "rate limit: reagendar com backoff" ;;
  500|502|503|504) echo "erro temporario: retry controlado" ;;
  401|403) echo "credencial ou permissao: parar e alertar" ;;
  *) echo "falha inesperada: guardar corpo e contexto" ;;
esac

O detalhe importante é “retry controlado”. Retry infinito é negação com loop. Você precisa de limite, intervalo progressivo e uma saída clara. Depois de algumas tentativas, pare, registre o que aconteceu e avise. Um sistema que falha rápido e explica bem é infinitamente melhor do que um sistema que fica patinando em silêncio.

Princípio 3: idempotência é a vacina contra duplicação vergonhosa

Idempotência significa poder rodar a mesma operação mais de uma vez sem criar bagunça. Em automações agendadas, isso não é luxo. É sobrevivência. Cron pode disparar duas vezes, um job pode ser retomado, uma chamada pode ficar sem resposta mesmo tendo sido processada, e você pode precisar repetir manualmente uma execução depois de corrigir uma falha.

Sem idempotência, a consequência aparece como posts duplicados, e-mails repetidos, cobranças em dobro, arquivos sobrescritos e aquela conversa triste no grupo: “ignorem a mensagem anterior”. Ninguém quer ser a pessoa que automatizou o constrangimento.

Use chaves naturais sempre que possível: slug de post, hash do conteúdo, ID externo, data mais categoria, nome normalizado do arquivo. Antes de criar algo, busque se já existe. Antes de enviar algo, registre uma intenção. Depois de concluir, registre o resultado. Essa trilha transforma repetição em retomada, não em duplicação.

CREATE TABLE automation_runs (
  id INTEGER PRIMARY KEY,
  job_name TEXT NOT NULL,
  idempotency_key TEXT NOT NULL UNIQUE,
  status TEXT NOT NULL,
  created_at TEXT NOT NULL,
  finished_at TEXT,
  result_json TEXT
);

Princípio 4: logs precisam contar uma história, não vomitar ruído

Log bom responde três perguntas: o que o sistema tentou fazer, com quais dados relevantes e qual foi o resultado. Log ruim despeja variável aleatória sem contexto ou, pior, registra segredo. A linha entre observabilidade e vazamento é fina. Não coloque tokens, senhas, app passwords, cookies ou payloads sensíveis em log. Parece óbvio, mas muita gente só descobre isso depois de criar um arquivo chamado debug-final-agora-vai.log com metade da casa dentro.

Prefira logs estruturados. Mesmo em scripts simples, JSON por linha já ajuda muito. Ele permite filtrar por job, etapa, status, duração e chave de idempotência. Quando a rotina cresce, você agradece por não depender de leitura arqueológica.

{"level":"info","job":"publish_daily","step":"category_audit","category":"Lab da Garra","duration_ms":842}
{"level":"error","job":"publish_daily","step":"media_upload","http_status":413,"hint":"imagem grande demais"}

Não precisa transformar cada automação doméstica em plataforma de observabilidade. Mas precisa deixar migalhas suficientes para você reconstruir o caminho. O futuro você estará cansado, com pressa e menos paciente do que o atual. Seja gentil com essa pessoa.

Box perrengue: o pior bug de automação é o que dá certo pela metade. Um post publicado sem imagem, um backup criado mas não enviado, uma planilha atualizada sem notificação. O sistema parece ter funcionado, então ninguém olha. Dias depois, a conta chega. Para evitar isso, defina uma verificação final explícita: “o estado publicado existe, está acessível e contém os IDs esperados”. Sem verificação, não é sucesso; é palpite com autoestima.

Princípio 5: falhe em etapas pequenas e recuperáveis

Uma automação grande deve ser uma sequência de checkpoints. Coletar dados. Validar. Transformar. Criar recurso externo. Confirmar recurso. Publicar. Verificar. Notificar. Cada etapa precisa saber o que recebeu e o que entregou. Quando algo quebra, você descobre onde parou e pode retomar dali.

Isso muda a arquitetura até de scripts simples. Em vez de um arquivo linear com cem linhas que “faz tudo”, pense em funções com contratos pequenos. Não para satisfazer palestra de clean code. Para conseguir consertar às pressas sem derrubar o resto.

def run_job():
    context = audit_categories()
    draft = build_article(context)
    media_id = upload_featured_image(draft)
    post_id = publish_post(draft, media_id)
    published = verify_post(post_id)
    return published

A versão real pode continuar simples. O ganho está em nomear as fronteiras. Quando você dá nome para uma etapa, fica mais fácil medir, testar, pular, repetir e explicar. Código sem fronteira vira corredor escuro: dá para atravessar, mas qualquer barulho parece ameaça.

Princípio 6: configure alertas para ação, não para ansiedade

Um alerta deve pedir uma decisão. Se ele só diz “algo aconteceu”, ele vira ruído. Alertas ruins treinam você a ignorar o sistema. Alertas bons dizem: o que falhou, desde quando, qual impacto provável, qual foi a última etapa concluída e qual é o próximo comando seguro.

Não alerte para tudo. Uma tentativa temporária que se recuperou sozinha pode virar log. Uma falha definitiva precisa de alerta. Um atraso acima do normal talvez mereça aviso. Um job crítico sem execução por 24 horas merece atenção. O importante é que o alerta carregue contexto suficiente para reduzir o tempo de diagnóstico.

• Bom: “Publicação diária falhou no upload de mídia. HTTP 413. Imagem com 8,4 MB. Post ainda não criado.”
• Ruim: “Erro no script.” Obrigado, Sherlock.

Também vale criar alertas de sucesso para fluxos sensíveis, mas com moderação. Um resumo diário pode ser melhor do que vinte mensagens avulsas. Automação deve devolver atenção, não sequestrar.

Princípio 7: segredos não pertencem ao código

Credenciais em código são uma dívida com juros compostos. Enquanto o projeto é pequeno, parece prático. Depois alguém copia o arquivo, manda para um repositório, cola em uma conversa, grava em log ou deixa em backup. A senha que “era só local” ganha passaporte.

Use variáveis de ambiente, arquivos de configuração fora do repositório, cofres de segredo ou o mecanismo mais simples que o seu ambiente suporta. O ponto é separar o segredo da lógica. E, quando possível, use credenciais com escopo limitado. Se um token só precisa publicar posts, ele não deveria administrar usuários, plugins e temas.

export WP_USER="usuario@example.com"
export WP_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx"
python publish.py

Outra prática saudável: rotação. Se um segredo apareceu onde não deveria, troque. Não discuta com o passado. Ele já ganhou prints suficientes.

Princípio 8: teste o caminho triste, não só o caminho feliz

Todo mundo testa se funciona quando tudo funciona. Isso prova pouco. O teste que importa em automações é o caminho triste: API fora, credencial inválida, resposta incompleta, imagem ausente, categoria inexistente, payload recusado, arquivo corrompido, timeout, rede lenta. É chato. Também é onde mora o dinheiro.

Você não precisa de uma suíte corporativa para cada script. Pode começar com fixtures locais e simulações simples. Salve respostas reais de APIs, remova campos, altere status e veja se o script para no lugar certo. Se ele continua e publica lixo, você encontrou um bug antes do público. Isso é uma pequena vitória civilizatória.

def test_stop_when_category_missing():
    categories = []
    try:
        choose_category(categories, recent_posts=[])
    except RuntimeError as exc:
        assert 'categoria' in str(exc).lower()
    else:
        raise AssertionError('deveria parar sem categoria valida')

O objetivo não é cobrir 100% das linhas. É cobrir as decisões perigosas. Onde há dinheiro, publicação, exclusão, mensagem externa, credencial ou dado de usuário, coloque guarda. O resto pode amadurecer com o tempo.

Como aplicar isso em uma rotina real de publicação

Vamos pegar uma rotina concreta: publicar um artigo diário em um blog. Parece simples. Mas o fluxo toca várias superfícies: auditoria de categorias, escolha de tema, busca de imagens, upload de mídia, criação de tags, publicação e verificação. Cada etapa pode falhar de um jeito diferente.

Um desenho resiliente para esse fluxo teria estes checkpoints:

1. Buscar categorias reais da API e mapear nomes para IDs atuais.
2. Buscar posts recentes para evitar repetição editorial.
3. Escolher tema e registrar a decisão.
4. Buscar imagens com quantidade mínima e licença adequada.
5. Baixar imagem de capa e validar tamanho do arquivo.
6. Enviar mídia e confirmar ID retornado.
7. Criar ou localizar tags, sempre usando IDs inteiros.
8. Montar payload e validar campos obrigatórios.
9. Publicar como publish.
10. Consultar o post publicado e confirmar status final.

Perceba a obsessão com “confirmar”. Não basta mandar. Tem que verificar. Em automação, o verbo “enviei” é menos importante que “o destino confirmou”. Essa diferença parece pequena até você descobrir que o servidor aceitou a conexão e recusou o payload.

Checklist mínimo para sua próxima automação

Antes de colocar uma rotina em produção, passe por esta lista. Ela é curta de propósito. Se ficar longa demais, ninguém usa. Se ficar frouxa demais, não protege nada.

• Existe validação explícita das entradas?
• Chamadas externas tratam status HTTP diferentes?
• Há limite de retry e backoff?
• A operação principal é idempotente ou tem chave única?
• Logs registram etapa, status e contexto sem segredos?
• Falhas definitivas geram alerta acionável?
• Credenciais estão fora do código e têm escopo limitado?
• Existe verificação final do estado esperado?

Se a resposta for “não” para tudo, parabéns: você tem uma demonstração. Ainda não tem uma automação confiável. Demonstrações são úteis para aprender. Produção exige menos teatro e mais contenção.

O ponto de equilíbrio: não transforme tudo em plataforma

Existe um risco oposto: exagerar. Algumas pessoas leem sobre resiliência e decidem construir um Kubernetes emocional para renomear PDFs. Não precisa. A maturidade está em calibrar o esforço pelo impacto da falha.

Se a automação só organiza arquivos pessoais e pode ser rodada de novo sem prejuízo, mantenha simples. Se ela publica conteúdo, mexe com dinheiro, envia mensagens, altera dados ou depende de terceiros, coloque mais proteções. O peso da estrutura deve acompanhar o custo do erro.

Minha regra prática: quanto mais externa, irreversível e visível for a ação, mais validação e verificação ela merece. Ação interna e reversível pode ser leve. Ação pública e difícil de desfazer precisa ser chata. Chato, nesse caso, é elogio.

Links úteis para continuar cavando

Se você quer conectar este tema com outras frentes do AutoMente, explore também as editorias Lab da Garra, Mente Binária, Fortaleza Digital, Log de Erros, Produtividade Aumentada. Para contexto recente do blog, estes posts ajudam a mapear o tipo de problema que vale automatizar:

• Segurança de Webhooks com HMAC: Pare de Aceitar Qualquer POST Vestido de Integração
• Automação Resiliente com Python: Retries, Lockfile e Idempotência Sem Drama
• Triagem de Logs de Erro em Automações Python: Pare de Caçar Falha no Escuro
• Monitor de Foco com Python: Descubra Onde Seu Dia de Dev Está Vazando
• Central de Produtividade Aumentada: Como Montar uma Fila Diária com Python e SQLite

A melhor automação não é a mais esperta. É a que resolve um problema real, falha de forma compreensível e não obriga você a virar babá de script. Esse é o padrão que eu tento seguir, depois de já ter criado algumas pequenas bombas-relógio digitais com a confiança de quem não tinha lido o log.

Fechamento

automação resiliente é uma disciplina humilde. Ela começa quando você aceita que a rede falha, APIs mentem por omissão, dados chegam tortos e você mesmo vai esquecer por que escreveu aquela linha daqui a três semanas. O código então deixa de ser uma sequência de desejos e passa a ser um acordo com a realidade.

Agora me diz: qual automação você quer ver destrinchada aqui no AutoMente? Pode ser publicação, backup, agenda, IA, planilhas, WordPress, Telegram, e-mail ou aquele fluxo vergonhoso que você ainda faz no braço enquanto finge que está tudo bem.