Mensagens de erro úteis: diagnóstico, causa, impacto e caminho de recuperação

O que torna uma mensagem de erro realmente útil

Uma mensagem de erro útil não serve apenas para “avisar que deu errado”. Ela funciona como um mini-atendimento dentro da interface: ajuda a pessoa a entender o que aconteceu, por que aconteceu (ou o que provavelmente causou), qual é o impacto imediato e o que fazer agora para recuperar o fluxo. Quando a mensagem falha em qualquer uma dessas partes, o usuário tende a repetir a ação, abandonar a tarefa, abrir suporte ou criar soluções improvisadas (como tentar várias senhas, reenviar o formulário várias vezes ou recarregar a página).

Para ser útil, uma mensagem de erro precisa equilibrar duas coisas: precisão (não inventar causas) e orientação (não deixar a pessoa sem saída). Na prática, isso significa que o texto deve oferecer um diagnóstico claro do problema, indicar a causa com o nível de certeza adequado, explicitar o impacto e fornecer um caminho de recuperação acionável.

O modelo: diagnóstico, causa, impacto e caminho de recuperação

1) Diagnóstico: o que falhou, onde e em qual etapa

Diagnóstico é a identificação do problema em termos que o usuário reconhece. Ele responde: “o que exatamente não deu certo?”. Um bom diagnóstico aponta o objeto do erro (pagamento, upload, login, envio do formulário), e quando possível, o local (campo específico, etapa do checkout, item da lista).

• Ruim: “Erro ao processar solicitação.”
• Melhor: “Não foi possível enviar o formulário.”
• Ainda melhor: “Não foi possível enviar o formulário porque o arquivo anexado excede o limite.”

Perceba que o diagnóstico não precisa ser técnico. “Falha 500” pode existir como detalhe para suporte, mas não deve ser o diagnóstico principal para o usuário.

2) Causa: por que aconteceu (com honestidade sobre incerteza)

Causa é a explicação do motivo. Aqui existem dois riscos comuns: (a) culpar o usuário sem evidência (“você digitou errado”) e (b) ser vago demais (“algo deu errado”). O ideal é declarar a causa quando há certeza (por exemplo, validação de campo, limite de tamanho, formato inválido) e usar linguagem probabilística quando não há (instabilidade, indisponibilidade temporária, falha de rede).

Continue em nosso aplicativo

Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.

ou continue lendo abaixo...

Baixar o aplicativo

• Causa certa: “O CPF precisa ter 11 números.”
• Causa provável: “Parece que sua conexão caiu durante o envio.”
• Causa desconhecida (com transparência): “Não conseguimos identificar a causa agora.”

Quando a causa é interna (ex.: serviço indisponível), a mensagem deve assumir responsabilidade sem dramatizar. Evite frases que soem como desculpa genérica (“Pedimos desculpas pelo inconveniente”) sem oferecer ação.

3) Impacto: o que isso significa para o usuário agora

Impacto é a consequência prática: o que não foi concluído, o que foi ou não foi salvo, se houve cobrança, se a ação precisa ser refeita, se há risco de perda de dados. Essa parte reduz ansiedade e evita ações duplicadas.

• “Seu pagamento não foi concluído e nada foi cobrado.”
• “As alterações não foram salvas.”
• “Seu arquivo não foi enviado.”
• “Seu pedido foi criado, mas o e-mail de confirmação pode demorar alguns minutos.”

Impacto também pode incluir escopo: “Apenas este item foi afetado” vs. “Sua conta inteira está temporariamente indisponível”.

4) Caminho de recuperação: o próximo passo mais seguro

Recuperação é a instrução acionável que coloca o usuário de volta no fluxo. Pode ser um botão (“Tentar novamente”), uma alternativa (“Salvar como rascunho”), uma correção (“Use um arquivo .PDF de até 10 MB”), ou um desvio (“Escolha outro método de pagamento”).

O caminho de recuperação deve ser específico e proporcional ao problema. Se a pessoa precisa corrigir um campo, diga qual e como. Se é um problema temporário, ofereça retentativa e, quando útil, um tempo estimado ou um indicador de status.

• “Revise o número do cartão e tente novamente.”
• “Reduza o arquivo para até 10 MB ou envie em PDF.”
• “Tente novamente em alguns minutos ou use Pix.”
• “Copie este código e envie ao suporte: 8F2A.”

Tipos comuns de erro e como aplicar o modelo

Erros de validação (entrada inválida)

São erros em que o sistema sabe exatamente o que está errado. Aqui, a mensagem deve ser direta, apontar o campo e explicar a regra de forma operacional (o que digitar).

• Diagnóstico: “O e-mail está incompleto.”
• Causa: “Falta o domínio após o @.”
• Impacto: “Não conseguimos enviar o link de confirmação.”
• Recuperação: “Digite um e-mail como nome@dominio.com.”

Evite regras abstratas (“formato inválido”) sem exemplo. Prefira exemplos curtos e alinhados ao padrão local (ex.: CEP, CPF, telefone).

Erros de autenticação (login, senha, 2FA)

Esses erros exigem cuidado com segurança. Você pode orientar sem revelar informação sensível (por exemplo, não confirmar se um e-mail existe no sistema). Ainda assim, dá para oferecer recuperação clara.

• Diagnóstico: “Não foi possível entrar.”
• Causa (neutra): “Verifique seus dados e tente novamente.”
• Impacto: “Você continua desconectado.”
• Recuperação: “Tente novamente ou redefina sua senha.”

Quando houver bloqueio por tentativas, explicite o impacto e o tempo.

• “Por segurança, sua conta foi temporariamente bloqueada por 15 minutos após várias tentativas. Tente novamente mais tarde ou redefina sua senha.”

Erros de rede e instabilidade (temporários)

Quando o problema pode ser transitório, a mensagem deve evitar culpar o usuário e oferecer retentativa com segurança. Se houver risco de duplicidade (ex.: pagamento), o impacto precisa ser cristalino.

• “Não conseguimos concluir agora por instabilidade. Seu pedido não foi finalizado e nada foi cobrado. Tente novamente.”

Se a ação pode ser repetida sem risco, diga isso. Se não pode, diga o que verificar (ex.: extrato, e-mail, histórico).

Erros de permissão (acesso negado)

O usuário precisa entender se falta permissão, se o recurso não existe ou se precisa de outro papel/conta. A recuperação pode ser trocar de conta, pedir acesso ou voltar.

• “Você não tem permissão para acessar este relatório. Peça acesso ao administrador ou troque para uma conta com permissão.”

Quando possível, inclua um caminho direto: “Solicitar acesso”.

Erros de conflito e estado (algo mudou)

Exemplos: item esgotou, sessão expirou, dados foram alterados por outra pessoa, versão desatualizada. O diagnóstico deve indicar o que mudou e o impacto deve proteger o trabalho do usuário.

• “Sua sessão expirou e você foi desconectado. Para continuar, entre novamente. Suas alterações não salvas foram perdidas.”
• “Este item não está mais disponível. Removemos do carrinho. Escolha uma alternativa para continuar.”

Passo a passo prático para escrever mensagens de erro úteis

Passo 1: Identifique o evento de erro e classifique o tipo

Antes de escrever, descreva o erro em uma frase interna: “o que o usuário tentou fazer e o que falhou”. Em seguida, classifique: validação, autenticação, rede/temporário, permissão, conflito/estado, processamento interno.

Essa classificação ajuda a decidir o nível de detalhe e o tom: validação pede instrução específica; rede pede retentativa; permissão pede alternativa; autenticação pede cuidado com exposição.

Passo 2: Defina o diagnóstico em linguagem do usuário

Escreva o diagnóstico como se fosse o título da mensagem (mesmo que você não use título visual). Ele deve ser curto e inequívoco.

• Checklist do diagnóstico:
• Nomeia a ação? (enviar, pagar, salvar, entrar)
• Nomeia o objeto? (arquivo, pedido, mensagem, perfil)
• Aponta o local quando aplicável? (campo X, item Y)

Exemplo de rascunho: “Não foi possível salvar suas alterações.”

Passo 3: Declare a causa com o nível certo de certeza

Liste as causas possíveis e marque quais o sistema consegue afirmar. Se o sistema só sabe que “falhou”, use linguagem de probabilidade e não invente.

• Causa afirmativa (regra violada): “O arquivo está em .exe, que não é permitido.”
• Causa provável (ambiente): “Parece que você ficou sem conexão.”
• Causa desconhecida: “Não conseguimos identificar o motivo agora.”

Quando houver código de erro útil para suporte, coloque como detalhe secundário, não como mensagem principal.

Passo 4: Escreva o impacto para reduzir incerteza

Responda explicitamente:

• Foi salvo?
• Foi enviado?
• Foi cobrado?
• Precisa refazer?
• Há risco de duplicidade?

Exemplos:

• “Nada foi cobrado.”
• “Seu rascunho foi salvo automaticamente.”
• “O upload não começou.”
• “O pedido foi criado, mas o pagamento não foi confirmado.”

Passo 5: Escolha um caminho de recuperação principal e, se necessário, um secundário

Defina a ação mais provável de resolver o problema. Se houver duas rotas comuns, ofereça uma principal (mais segura) e uma secundária (alternativa). Evite listar muitas opções, porque isso vira “menu de suporte”.

• Recuperação principal: “Tentar novamente”
• Recuperação secundária: “Salvar e sair” / “Usar outro método” / “Falar com suporte”

Inclua requisitos concretos quando o usuário precisa corrigir algo: tamanho máximo, formato aceito, caracteres permitidos, prazo, etc.

Passo 6: Ajuste para o contexto visual (inline, toast, modal, página)

O mesmo conteúdo muda conforme o componente:

• Inline (em campo): foque em diagnóstico + recuperação (“Digite 11 números”).
• Toast: foque em diagnóstico + impacto curto + ação (“Falha ao salvar. Tentar novamente”).
• Modal: bom para impacto relevante e escolha de caminhos (ex.: risco de perda de dados).
• Página de erro: permite detalhar causa provável, status, alternativas e contato.

Evite colocar instruções longas em componentes que somem rápido (toast). Se precisar, direcione para um local persistente (ex.: “Ver detalhes”).

Passo 7: Teste com cenários reais e revise para ambiguidade

Faça um teste de mesa com 5 perguntas:

• O usuário entende o que falhou sem ler duas vezes?
• Ele sabe se perdeu algo?
• Ele sabe o que fazer agora?
• Há risco de ele repetir e piorar (duplicar pedido, enviar duas vezes)?
• A mensagem evita promessas que o sistema não garante?

Exemplos prontos (antes e depois) usando o modelo

Upload de arquivo

Antes: “Arquivo inválido.”

Depois: “Não foi possível enviar o arquivo. Ele tem 18 MB e o limite é 10 MB. Reduza o tamanho ou envie um PDF de até 10 MB.”

Pagamento recusado

Antes: “Transação não autorizada.”

Depois: “O pagamento não foi aprovado pelo banco. Nada foi cobrado. Tente novamente, use outro cartão ou escolha Pix.”

Erro interno ao salvar

Antes: “Erro 500.”

Depois: “Não conseguimos salvar suas alterações agora. Suas mudanças ainda não foram salvas. Tente novamente. Se continuar, copie o código 8F2A e fale com o suporte.”

Sessão expirada

Antes: “Sessão inválida.”

Depois: “Sua sessão expirou por inatividade e você foi desconectado. Entre novamente para continuar. As alterações não salvas não foram mantidas.”

Permissão insuficiente

Antes: “Acesso negado.”

Depois: “Você não tem permissão para editar este projeto. Peça acesso ao administrador ou abra em modo de visualização.”

Detalhes que aumentam a utilidade sem alongar demais

Use dados concretos quando isso ajuda a corrigir

Quando o sistema tem a informação, ela acelera a correção:

• “Você anexou 12 arquivos; o limite é 5.”
• “O código tem 4 dígitos; o esperado é 6.”
• “Seu plano permite até 3 usuários; você já tem 3.”

Evite linguagem que gera atrito ou culpa

Troque acusações por descrições verificáveis:

• Em vez de “Você digitou errado”, prefira “Não encontramos uma combinação válida. Verifique e tente novamente.”
• Em vez de “Você não tem autorização”, prefira “Sua conta não tem permissão para…”

Quando houver espera, diga o que o usuário pode fazer enquanto isso

Se o processo demora, a mensagem pode orientar sem prometer prazos exatos:

• “Estamos processando seu pagamento. Isso pode levar alguns minutos. Você pode acompanhar em ‘Pedidos’.”

Inclua suporte de forma eficiente

Quando a recuperação depende de suporte, facilite a triagem:

• Forneça um identificador (código, ID do pedido, horário).
• Indique o canal apropriado (chat, e-mail) e o que enviar.

Exemplo: “Se continuar, envie ao suporte o código 8F2A e o horário aproximado da tentativa.”

Checklist operacional para equipes (copiar e usar)

Mensagem de erro útil (D-C-I-R) - checklist rápido

[ ] Diagnóstico: diz o que falhou (ação + objeto) e onde (se aplicável)
[ ] Causa: afirma apenas o que o sistema sabe; usa “parece/possivelmente” quando necessário
[ ] Impacto: deixa claro o que foi/ não foi concluído (salvo, enviado, cobrado)
[ ] Recuperação: oferece um próximo passo acionável (principal) e alternativa (se necessário)
[ ] Segurança: não expõe dados sensíveis nem confirma existência de conta indevidamente
[ ] Persistência: o usuário consegue reler (ou há “ver detalhes”) quando o erro é complexo
[ ] Prevenção de duplicidade: orienta quando NÃO repetir a ação (ex.: pagamento)

Mapeando o conteúdo da mensagem para componentes comuns

Inline (no campo)

• Estrutura: diagnóstico + recuperação
• Exemplo: “Use apenas números (11 dígitos).”

Banner no topo da página

• Estrutura: diagnóstico + impacto + recuperação
• Exemplo: “Não foi possível enviar. Nada foi salvo. Revise os campos destacados e tente novamente.”

Toast/Notificação rápida

• Estrutura: diagnóstico curto + ação
• Exemplo: “Falha ao salvar. Tentar novamente.”

Modal de decisão

• Estrutura: diagnóstico + impacto + dois caminhos
• Exemplo: “Você tem alterações não salvas. Se sair agora, elas serão perdidas. Continuar editando ou sair sem salvar?”

Página de erro (ex.: indisponibilidade)

• Estrutura: diagnóstico + causa provável + impacto + alternativas + suporte
• Exemplo: “Estamos com instabilidade. Algumas ações podem falhar. Tente novamente em alguns minutos ou acompanhe o status. Se for urgente, fale com o suporte e informe o código…”