Tipos de erros em programação: 6 categorias e 8 exemplos

Erros de programação se dividem em seis famílias: sintaxe, execução, referência, rede, lógica e ambiente ou configuração. O valor da classificação não está no vocabulário, e sim no fato de cada família deixar evidências diferentes. Saber a família indica qual mensagem, qual requisição e qual captura de tela um relato de bug precisa. Este artigo traz primeiro uma tabela para usar direto, depois percorre os oito erros front-end mais comuns — mostrando que um mesmo erro pode cair em várias famílias — e termina na parte prática: como um erro vira um relato que o desenvolvedor consegue resolver sem fazer três perguntas.

Por que a classificação merece um artigo

A maioria dos times não tem dificuldade em entender o que TypeError significa. Tem dificuldade com outras três coisas:
  • chamar de bug toda linha vermelha do console, quando metade vem de scripts de terceiros e extensões do navegador;
  • repassar "a página não faz nada" direto para o back-end, quando o front-end nunca tratou o formato da resposta;
  • registrar um relato que diz "deu erro" e deixar o desenvolvedor vinte minutos perguntando qual página, qual navegador e o que foi clicado.
Os três são problemas de classificação: a família determina a evidência, e a evidência determina se o relato pode ser corrigido diretamente.

As seis famílias

Família Quando acontece Mensagem típica Onde está a evidência primária
Sintaxe O código não pode ser interpretado, todo o script para Unexpected token, Unexpected end of input A primeira linha vermelha do console (o resto costuma ser efeito em cadeia)
Execução O código roda e falha em um passo TypeError, RangeError, Cannot read properties of undefined Console mais a ação que disparou
Referência Usa uma variável, campo ou módulo inexistente ReferenceError, x is not defined, undefined is not a function Console mais a URL (qual rota não carregou)
Rede A requisição falha, é bloqueada, é cross-origin ou expira 4xx / 5xx, blocked by CORS policy, net::ERR_ Painel Rede: URL, código de status, cabeçalhos da resposta
Lógica Nada lança erro, mas o resultado está errado Nenhum texto vermelho Passos, resultado esperado vs real, uma amostra de dados
Ambiente Só em uma máquina, um ambiente ou uma conta 404 sem relação, tela branca, recursos que não carregam Versão de navegador e sistema, viewport, marcador de build ou ambiente, permissões da conta
A coluna mais útil é a última: ela diz o que colocar no relato. Um erro de lógica não tem mensagem para capturar, então precisa de passos e expectativa. Um erro de rede não se explica com captura de tela, então precisa da requisição.

Sintaxe, execução, lógica: as fronteiras são difusas

Uma mesma mensagem pode pertencer a famílias diferentes conforme a causa, não conforme o texto. Uncaught TypeError: Cannot read properties of undefined (reading 'map') é um erro de execução: o código chegou a um undefined e chamou .map nele. Mas a causa pode ser:
  • o formato da resposta da API mudou (rede);
  • o estado inicial está sem um valor padrão (lógica);
  • uma requisição assíncrona não havia voltado antes da renderização (timing).
Por isso "lança um TypeError" não basta. O relato precisa da requisição de onde vieram os dados. É também por isso que erros de console e requisições com falha andam juntos: qualquer um dos dois sozinho leva a conclusão errada.

Os oito erros front-end mais comuns

# Mensagem Costuma significar Onde olhar
1 TypeError: Cannot read properties of undefined Os dados não chegaram, o formato não bate, falta optional chaining Console mais a resposta da requisição correspondente
2 ReferenceError: x is not defined Variável não declarada, ordem de scripts errada, módulo fora do bundle Console mais a ordem dos scripts no código-fonte
3 blocked by CORS policy Preflight falhou ou falta Access-Control-Allow-Origin Console mais a requisição de preflight no painel Rede
4 Um endpoint retorna 404 / 500 Caminho errado, recurso removido, exceção no servidor Rede: URL, código de status, resumo da resposta
5 Hydration failed because the initial UI does not match Servidor e cliente renderizaram primeiras telas diferentes Console mais o componente envolvido
6 Unhandled promise rejection Falha assíncrona sem catch, o erro desaparece Console mais a ação que disparou
7 Refused to load ... violates Content Security Policy A CSP não libera um domínio novo ou script inline Console mais o cabeçalho CSP da página
8 Mixed Content: ... loaded over HTTPS, but requested an insecure resource Página HTTPS pede um recurso HTTP Console mais a requisição bloqueada no painel Rede
Sirva como checklist: classifique a linha vermelha primeiro, depois acrescente a evidência indicada à direita.

Erro, bug e defeito não são a mesma coisa

  • Um erro é um sinal do sistema. Pode ser um aviso; pode ser ruído.
  • Um bug é uma divergência entre implementação e expectativa e normalmente exige um caminho reproduzível.
  • Um defeito é o que a maioria das ferramentas chama de bug quando ele entra na gestão formal.
A distinção completa está em Bug vs Defect vs Issue vs Error. Para quem relata, uma frase basta: erro é pista, bug é conclusão. O relato fornece pistas, não veredito.

Que evidência cada família precisa

Família O relato deve conter Útil, não obrigatório
Sintaxe / execução Mensagem exata, URL, ação que disparou Captura, gravação curta
Referência Mensagem exata, rota que falhou, papel logado Formato da resposta relacionada
Rede URL da requisição, código de status, ação, horário Trecho da resposta (com campos sensíveis mascarados)
Lógica Passos, resultado esperado, resultado real, amostra de dados Gravação de tela
Ambiente Versão de navegador e sistema, viewport, marcador de ambiente (produção, staging, preview) Permissões da conta, número do build
A última linha é a mais ignorada: "só acontece na minha máquina" é, por si só, a informação mais valiosa do relato, porque reduz a busca do site inteiro para uma classe de ambiente.

Conseguir a evidência sem interrogatório

O caminho manual é abrir o DevTools, capturar o console e o painel Rede e alinhar horários na mão — veja Como abrir o console do navegador. Esse caminho tem três problemas práticos: colegas não técnicos não vão fazer, não vão capturar tudo, e alguém terá de conciliar os horários depois. O caminho barato é deixar a ferramenta de relato carregar isso. Todo relato do BugCapturer anexa a URL da página (com parâmetros sensíveis mascarados), navegador e sistema, tela e viewport, horário, os erros de console literais e as requisições com falha (4xx/5xx) com o código. A pessoa marca a área e escreve uma frase sobre o que viu; as outras cinco colunas chegam sozinhas. A diferença aparece na taxa de envio. Exigir que alguém aprenda o console deixa de fora a maioria dos colegas não técnicos; anotar direto na página faz com que enviem um segundo relato.

Precisa de um campo "tipo de erro"?

Se o registro já tem algumas centenas de relatos, um campo error_type se paga — mas só em três situações:
  • A mesma família volta (um CORS a cada duas semanas): a classificação expõe um problema sistêmico em vez de um ticket por vez.
  • Quem relata não é desenvolvedor: a classificação elimina a ida e volta "front ou back".
  • Vocês medem qualidade: a distribuição por tipo é mais justa que por pessoa.
  • Se o time tem três a cinco pessoas e menos de vinte relatos por semana, o campo só adiciona digitação. Primeiro complete a evidência; depois fale de classificação.

    Três erros comuns

    • Tratar toda linha vermelha como bug: extensões, scripts de analytics e bloqueadores escrevem no console. O critério é se aquilo muda o comportamento da página.
    • Ignorar avisos: avisos de key do React, de hidratação e de depreciação não são bugs, mas costumam anunciá-los.
    • Encaminhar um 500 direto ao back-end: o código diz que o servidor falhou, mas faltam a URL, os nomes dos parâmetros e a ação. Sem esses três, a resposta será sempre "reproduza".

    FAQ

    Erro de sintaxe é bug? No código-fonte, normalmente não chega à produção: o build barra. Se um SyntaxError aparecer em produção, o problema está na esteira de publicação — build sem validação ou CDN servindo arquivo antigo — e deve ser tratado como defeito. Os avisos do console devem entrar no relato? Só os relacionados ao sintoma. Tela branca com aviso de hidratação, sim; aviso de depreciação de uma biblioteca, não, porque enterra a pista real. Um "API 500" é front-end ou back-end? Quem corrige depende do processo, mas o conteúdo do relato é o mesmo: URL, código de status, ação, horário e se reproduz. Primeiro confirme se o front-end enviou parâmetros errados ou se o servidor falhou de fato. Por que o desenvolvedor sempre diz "não consigo reproduzir"? Porque o que falta é ambiente, não passos: permissões, volume de dados, versão de navegador, fuso horário e feature flags variam. Um campo de ambiente no relato elimina essa rodada. Como colegas não técnicos produzem relatos úteis? Não ensine DevTools. Instale uma extensão do navegador ou embuta um ponto de entrada de feedback no site e deixe a ferramenta coletar console e requisições com falha — é a premissa de um sistema de feedback instantâneo.