O Que Seu App Deve Dizer Quando Algo Dá Errado: Escrevendo Mensagens de Erro Que as Pessoas Realmente Entendem

Todo app quebra às vezes. A internet cai, um servidor engasga, alguém digita um número de telefone com letras no meio. Essa parte você não consegue evitar totalmente. O que você pode controlar é a mensagem de erro — o texto que seu app mostra quando algo dá errado — e essa única mensagem é, muitas vezes, a diferença entre um usuário que dá de ombros e tenta de novo, e um usuário que decide, em silêncio, que seu app está quebrado e nunca mais volta.

A maioria dos apps criados com IA erra exatamente nesse momento. Não porque o builder foi descuidado, mas porque mensagens de erro são a parte em que ninguém pensa até que algo dê errado na frente de uma pessoa de verdade. Por padrão, os apps costumam mostrar uma das duas piores coisas possíveis: nada, ou um bloco assustador de texto técnico. Vamos consertar os dois.

Por que os apps falham em silêncio ou mostram mensagens de erro assustadoras?

Os apps quebram mal de duas formas: não dizem nada quando algo falha, ou mostram um erro técnico que uma pessoa comum não consegue ler. As duas deixam o usuário adivinhando, e é a adivinhação que faz as pessoas desistirem.

A falha silenciosa. Uma freelancer que vou chamar de Maya criou um formulário de agendamento para o seu negócio de fotografia. Uma cliente tocou em “Confirmar Agendamento”, o botão piscou e… nada. Sem confirmação, sem erro, sem indicador de carregamento. Funcionou? A cliente não tinha certeza, então agendou de novo. Agora Maya tinha dois agendamentos para o mesmo horário e uma cliente confusa. O app não travou — o salvamento simplesmente falhou, e o app não disse nada, então a pessoa na frente da tela não fazia ideia do que era real.

O erro técnico assustador. A outra falha é mais barulhenta e, de certa forma, pior. Uma voluntária que organizava uma arrecadação de fundos comunitária tentou enviar uma planilha e recebeu uma caixa vermelha dizendo Error 500: Internal Server Error. Ela leu aquilo como “eu quebrei alguma coisa”. Não tentou de novo, não mandou e-mail pedindo ajuda, só fechou a aba — porque a mensagem fazia o problema parecer culpa dela e dava a impressão de que talvez não fosse seguro mexer de novo.

Os dois usuários enfrentaram um problema normal e recuperável. Os dois desistiram, porque as mensagens de erro do app ou não disseram nada, ou disseram algo assustador.

O que faz uma boa mensagem de erro?

Uma boa mensagem de erro faz quatro pequenas coisas, em palavras simples: diz o que aconteceu, diz de quem é o problema, diz o que fazer a seguir, e não perde o trabalho do usuário.

Diz o que aconteceu — “Não conseguimos salvar seu agendamento”, não silêncio e não 500.
Diz de quem é o problema — geralmente a resposta honesta é “nosso”, e dizer isso acalma as pessoas.
Diz o que fazer a seguir — “Tente novamente em instantes” ou “Verifique sua conexão com a internet e tente de novo”.
Não perde o trabalho delas — o que quer que tenham digitado ainda está no formulário quando a mensagem aparece.

É só isso. Nada de ensaio de desculpas, nada de código de erro como título principal, nada de culpa. Aqui estão as mesmas três falhas, reescritas:

❌ (nada acontece) → ✅ “Não conseguimos salvar isso agora. Seus dados ainda estão aqui — toque em Confirmar para tentar de novo.”
❌ Error 500: Internal Server Error → ✅ “Algo deu errado do nosso lado ao enviar esse arquivo. Não é você. Tente de novo daqui a um minuto.”
❌ Invalid input → ✅ “Esse número de telefone não parece certo — deve ter 10 dígitos, tipo 555-123-4567.”

Perceba que o último exemplo aponta para o campo específico e mostra como o formato correto deveria ser. “Invalid input” faz a pessoa ter que adivinhar; “esse número de telefone deveria ter 10 dígitos” diz exatamente o que mudar.

Quais erros do app você deve corrigir primeiro?

Você não precisa de uma mensagem personalizada para cada falha possível — três casos cobrem quase tudo que dá errado em um app típico: o salvamento ou envio que falha, a entrada que o app não consegue usar, e algo que quebra do seu lado.

O salvamento ou envio que falha. O mais destruidor de confiança, porque o usuário fez tudo certo e não tem certeza se funcionou. Sempre confirme o sucesso e explique a falha. Nunca deixe a pessoa adivinhando, e nunca jogue fora o que ela digitou.

O “não conseguimos usar o que você digitou” (validação). Isso não é bem um erro — é um mal-entendido. Perceba no momento em que a pessoa sai do campo, aponte para o campo exato, e mostre um exemplo do formato correto. Não espere até que ela clique em Enviar para revelar uma parede de vermelho.

O “algo do nosso lado quebrou”. Problemas reais de servidor ou de rede. Diga que é do seu lado, mantenha a calma, e ofereça uma nova tentativa. O usuário não pode consertar seu servidor, então não o faça sentir que precisa.

Três hábitos que ajudam discretamente

Algumas coisas separam os apps que lidam bem com falhas dos que não lidam:

Nunca mostre um código de erro puro como a mensagem inteira. Um código pode ficar em letras pequenas embaixo, para o suporte, mas o título que uma pessoa lê deve ser uma frase, não ERR_CONN_RESET.
Nunca culpe o usuário. “Você digitou algo errado” incomoda; “essa data parece estar no passado — você quis dizer o próximo mês?” ajuda. Mesma informação, sensação completamente diferente.
Sempre mantenha o que a pessoa digitou. Se o app recarrega ou o salvamento falha e o formulário fica em branco, você transformou um pequeno tropeço em dez minutos de retrabalho. As pessoas perdoam um salvamento que falhou. Elas não perdoam ter que fazer o trabalho duas vezes.

Como fazer seu AI builder escrever mensagens de erro melhores?

Você consegue resolver quase tudo isso em um único pedido — cole algo como o prompt abaixo e seu AI builder vai aplicar as regras de linguagem simples acima em todo o seu app.

“Quando um salvamento ou envio falhar, não falhe em silêncio e não mostre um código de erro técnico. Mostre uma mensagem curta e amigável, em linguagem simples, que diga o que aconteceu, diga que está tudo bem tentar de novo, e mantenha o que o usuário já digitou. Para campos de formulário, valide assim que o usuário sair de cada campo e mostre uma mensagem específica com um exemplo do formato correto.”

Depois, peça para ele te mostrar o que acontece em três casos: a internet está desligada, um campo obrigatório está em branco, e o servidor está lento. Se a resposta para qualquer um deles for “não mostra nada” ou “mostra o erro bruto”, é aí que você deve corrigir primeiro.

Como testar as mensagens de erro do seu app?

Desligue seu wifi, abra seu app, e tente fazer a ação principal — esse é o teste inteiro, e leva dois minutos.

Reserve o horário, salve a anotação, envie o arquivo. Veja o que aparece. Isso disse algo que uma pessoa comum entenderia? Perdeu o que você tinha digitado? Agora ligue o wifi de novo e digite propositalmente algo inválido em um campo. As mesmas perguntas.

A maioria dos apps falha nesse teste na primeira vez, e tudo bem — isso só mostra exatamente por onde começar. Você não precisa deixar cada mensagem de erro perfeita. Encontre a coisa que mais quebra no seu app, e faça essa mensagem gentil, clara e honesta primeiro. Da próxima vez que uma pessoa de verdade encontrar esse erro, ela vai tentar de novo em vez de ir embora — e tentar de novo é o jogo inteiro.