Contexto
Um código de erro é um identificador criado para diagnóstico, suporte ou rastreamento técnico. Ele não explica, por si só, o que a pessoa pode fazer. Por isso, a pergunta não é se códigos são bons ou ruins, mas se aquele código ajuda este público a recuperar-se ou a pedir ajuda.
Em uma interface para o público geral, a mensagem principal deve traduzir o impacto da falha e indicar o próximo passo. O código pode aparecer como referência secundária quando houver uma equipe de suporte, um incidente persistente ou uma necessidade real de localizar a ocorrência.
Comece pelo que a pessoa precisa saber: o que não aconteceu, se a operação foi concluída e qual ação é segura. Prefira “Não foi possível salvar o arquivo. Tente novamente” a “Erro 500”.
Mostre um código somente quando ele tiver uma função clara, como acelerar o atendimento ou localizar uma ocorrência persistente. Apresente-o depois da mensagem principal, com um rótulo compreensível — por exemplo, “Código de referência: 8F4K2” — e permita copiá-lo sem exigir que a pessoa o interprete.
Use identificadores curtos, estáveis e não sensíveis. Correlacione o código com logs, horário, conta e rastreamento no ambiente interno, sem revelar esses dados na interface. Se a operação puder ter sido concluída, informe como consultar o status antes de sugerir uma nova tentativa.
Separe a resposta para a interface do contrato técnico da API. Para integrações, um formato estruturado pode transportar tipo, título, status, detalhe seguro e identificador da ocorrência; a interface não precisa expor a resposta bruta, a stack trace ou a exceção interna.
Em autenticação, recuperação de conta e outros fluxos sensíveis, use mensagens genéricas quando detalhes diferentes puderem revelar a existência de uma conta, um recurso ou uma regra interna.
Porque isso importa?
Códigos podem reduzir o tempo de suporte quando são usados como referência compartilhada, mas acrescentam pouco para quem só precisa concluir uma tarefa. Colocá-los no início da mensagem desloca a atenção para uma informação que a maioria das pessoas não sabe interpretar.
O W3C orienta identificar erros em texto e oferecer sugestões quando conhecidas. Isso exige uma explicação compreensível e uma saída, não apenas um número. A orientação do Adobe Spectrum converge com essa distinção: o código pode aparecer quando for útil e deve ficar no final da mensagem.
Detalhes técnicos também podem expor informações sobre a implementação ou ajudar ataques de enumeração. A recomendação, portanto, combina clareza para a pessoa, segurança na exposição e rastreabilidade para a equipe — sem transformar o usuário em depurador.
Quando usar?
- Quando o suporte precisa localizar a ocorrência.
- Quando a falha persiste ou afeta muitas pessoas.
- Quando há um canal de atendimento disponível.
- Quando o código é curto e não revela dados.
- Quando o público conhece o domínio técnico.
- Quando a operação exige investigação posterior.
Quando evitar?
- Em erros simples que a pessoa consegue corrigir.
- Em validações de campos.
- Quando o código não leva a nenhuma ação.
- Quando expõe stack trace ou sistema interno.
- Em autenticação com risco de enumeração.
- Quando a mensagem desaparece antes de ser copiada.
Recomendações
Faça
- Explique o impacto.
- Indique o próximo passo.
- Mostre o código depois.
- Rotule a referência.
- Permita copiar.
- Registre o contexto internamente.
- Preserve o estado da operação.
- Teste com o suporte.
Evite
- Não comece pelo número.
- Não mostre stack trace.
- Não exiba dados internos.
- Não use código sem suporte.
- Não culpe a pessoa.
- Não dependa de cor.
- Não revele contas válidas.
- Não peça interpretação técnica.
