Contratos de erro e semântica de falha sem exceção genérica para tudo

O problema

Backend sem contrato de erro claro costuma cair em dois extremos:

• tudo vira exceção genérica
• tudo vira catálogo enorme de códigos que ninguém usa direito

Nos dois casos, o sistema perde uma coisa importante:

a capacidade de reagir com critério ao tipo de falha que aconteceu

Sem isso, cada camada inventa sua própria leitura.

Modelo mental

Erro técnico e semântica de falha não são exatamente a mesma coisa.

O erro técnico pode ser:

• timeout
• conexão recusada
• resposta inválida

A semântica que interessa para o fluxo costuma ser algo como:

• falha transitória
• falha permanente
• dado inválido
• regra de negócio negada
• sistema em estado parcial

É essa leitura que ajuda a decidir o próximo passo.

O que costuma precisar ficar explícito

Um contrato de erro útil normalmente responde:

• isso pode ser tentado de novo?
• isso é erro do chamador ou do sistema?
• isso merece fallback?
• isso pede ação manual?

Sem essa camada, o fluxo acima só recebe ruído.

Exemplo simples

Imagine um caso de uso que chama um provedor antifraude.

O provider pode devolver:

• 429
• timeout
• documento inválido
• usuário bloqueado por política

Se tudo isso sobe como AntiFraudError, a orquestração não sabe distinguir:

• insistir depois
• corrigir input
• bloquear pedido
• degradar fluxo

O problema não é só de nomenclatura.

É de decisão.

O erro comum

O erro comum é achar que contrato de erro significa criar vinte subclasses e acabou.

Não necessariamente.

Às vezes o suficiente é um conjunto pequeno e útil de semânticas:

• transient_failure
• validation_failure
• business_denied
• unexpected_internal_failure

O ponto não é modelar o universo inteiro.

É dar ao sistema um vocabulário pequeno, estável e acionável.

Onde isso costuma morar

Normalmente, a borda traduz o erro técnico bruto.

Depois, a camada de aplicação trabalha com semântica mais estável.

Assim o núcleo não precisa conhecer:

• código estranho do provider
• texto de exceção de biblioteca
• payload opaco de integração

Ele só precisa saber o que aquilo significa para o fluxo.

Como um senior pensa

Quem tem mais julgamento costuma perguntar:

• este erro muda o quê no comportamento do sistema?
• qual camada tem contexto para traduzir isso direito?
• quantas categorias eu realmente preciso para tomar boas decisões?
• estou modelando falha para agir melhor ou só para parecer elegante?

Essa última pergunta economiza bastante teatro.

Ângulo de entrevista

Esse tema aparece em backend, integração e system design.

O entrevistador quer ver se você entende:

• que nem toda falha é igual
• que retry e fallback dependem da semântica da falha
• que contrato de erro serve para decisão, não para ornamentação OO

Resposta forte costuma soar assim:

“Eu não deixaria a camada central reagir a string de exceção ou código cru de provider. Traduziria isso em poucas semânticas úteis, como falha transitória, erro de validação ou negativa de regra, porque é isso que realmente muda a reação do sistema.”

Takeaway direto

Contrato de erro bom não deixa o sistema mais verboso.

Deixa o sistema menos perdido quando algo quebra.