Mensagens de erro que dizem a usuários e agentes o que fazer a seguir

O que é

Uma mensagem de erro é a resposta da interface a duas perguntas que o curso do Google sobre mensagens de erro (citado) coloca no centro: o que deu errado e como o usuário corrige. As regras do curso são explicar o problema, identificar a causa e a entrada inválida, especificar requisitos e restrições e explicar a solução. A orientação da Microsoft (citada) pede que a mensagem apresente um problema, uma causa e uma solução, e que seja escrita do ponto de vista do usuário. Quando a mensagem é lida por um programa ou por um agente, esse mesmo conteúdo precisa estar disponível em campos, e não apenas em texto corrido.

Por que importa

Uma mensagem vaga ("Invalid request") gera um chamado de suporte, um palpite ou, no caso de um cliente automatizado, um ciclo de novas tentativas idênticas. Muitas vezes a mensagem é a única documentação que o leitor tem naquele momento. A abordagem do compilador do Rust (citada) mostra até onde isso pode ir: os diagnósticos trazem sugestões estruturadas rotuladas com um nível de aplicabilidade (MachineApplicable, HasPlaceholders, MaybeIncorrect, Unspecified), de modo que as ferramentas aplicam automaticamente apenas as marcadas como aplicáveis de forma mecânica.

Como aplicar

• Nomeie o elemento: o campo, o arquivo e a linha, o valor realmente recebido e o que era esperado no lugar ("start_date: expected an ISO 8601 date such as 2026-09-15, got 15.09.2026").
• Declare a restrição, e não apenas a falha: o limite, o conjunto permitido, o formato exigido.
• Diga o que fazer a seguir e se repetir a mesma ação pode funcionar: distinga explicitamente entre "corrija a entrada", "aguarde e tente novamente" e "entre em contato com o operador".
• Dê a cada causa distinta a sua própria mensagem e um identificador estável e pesquisável; mantenha o identificador constante entre versões, mesmo quando o texto melhorar.
• Para agentes e clientes, forneça as partes como campos: código, campo, valor esperado, valor recebido, se pode ser repetida (retryable) e link para a documentação; o formato Problem Details para APIs HTTP (veja o artigo relacionado) é um dos meios de transporte possíveis.
• Mantenha as correções sugeridas separadas da descrição do erro e indique o grau de confiança de cada uma, como faz o guia do Rust; uma sugestão errada aplicada automaticamente é pior do que nenhuma.
• Nunca exponha detalhes internos a usuários finais (stack traces, nomes de host, SQL, segredos); registre-os em log com um ID de correlação que a mensagem exibe.
• Escreva em linguagem simples, sem culpar o usuário, sem dupla negação e sem humor; teste cada mensagem perguntando "o que eu faria agora?".

Armadilhas

Mensagens genéricas que escondem a causa. Mensagens cujo texto muda a cada versão e quebra parsers. Sugestões que erram mais do que acertam. Erros de validação reportados um de cada vez quando o cliente enviou dez campos. Revelar se uma conta existe por meio de mensagens diferentes para "senha incorreta" e "usuário desconhecido".