Histórico e Alertas de Erro

O Histórico e Alertas de Erro é o recurso responsável por capturar, padronizar e disponibilizar os detalhes de qualquer falha ou exceçãocorrida durante a execução de um fluxo.

Quando um runner ou a própria Engine identifica uma inconsistência de negócio, erro de sintaxe, falha de validação ou indisponibilidade de integração externa, o ciclo de execução é interrompido de forma controlada, alimentando o histórico da sessão e gerando alertas para diagnósticos e auditorias.

O Ciclo de Tratamento de Exceções (`InterrupcaoException`)

O tratamento de falhas na Engine segue um fluxo unificado e transacional para garantir que nenhum erro ocorra de forma silenciosa no ambiente:

[ Inconsistência na Etapa / Runner ] ──► Lança InterrupcaoException
                                                    │
                                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        TRATAMENTO NA ENGINE                            │
│  1. Interrompe a execução normal do pipeline                           │
│  2. Define emExecucao = FALSE no contexto da transação                 │
│  3. Gera Alerta na Sessão                                              │
│  4. Grava Container de Erro no Histórico de Sessão                     │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        FORMATAÇÃO DE SAÍDA                             │
│  - Avalia o Adaptador de Erro (ERRO_FULL, ERRO_BOLEANO, ERRO_SUPPRESS) │
│  - Devolve resposta HTTP (ex: 400 Bad Request, 500 Internal Error)     │
└────────────────────────────────────────────────────────────────────────┘

Estrutura do Container de Erro

As exceções capturadas são encapsuladas em um formato padronizado de container de erro (ContainerExcecaoDeExecucao). Isso permite que a Engine trate tanto exceções internas mapeadas quanto erros não previstos de integração:

Código de Erro (codigo): Identificador técnico e único do tipo de erro (ex: ETAPA_NAO_ENCONTRADA, VALIDACAO_ENTRADA_FALHOU, TIMEOUT_INTEGRACAO).
Mensagem (mensagem): Descrição textual amigável explicando o motivo da interrupção.
Detalhes (detalhes): Objeto com informações detalhadas para depuração (ex: lista de campos do formulário que falharam na validação por Regex ou o corpo de resposta de erro retornado por uma API externa).
Timestamp (horario): Data e hora exatas da ocorrência da falha.

Formatação da Resposta de Erro no Cliente

A quantidade de detalhes sobre a falha exposta ao cliente HTTP final na resposta da requisição depende da configuração dos Adaptadores de Saída cadastrados para aquele grupo no escopo ERRO:

`ERRO_FULL`

Retorna o objeto de erro completo estruturado no corpo da resposta HTTP (incluindo código, mensagem e detalhes técnicos). Recomendado para ambientes de desenvolvimento e homologação.

`ERRO_BOLEANO`

Retorna apenas uma chave booleana (ex: "erro": true) sem detalhar os motivos internos, preservando a segurança em APIs públicas.

`ERRO_SUPPRESS`

Oculta completamente a estrutura de erro do corpo de resposta HTTP.

Consulta e Diagnóstico de Falhas

Para depuração de erros em tempo de execução, a plataforma oferece dois caminhos principais de inspeção:

Inspeção por ID de Sessão (GET /v1/core/info/{idSessao})

Permite consultar o estado da sessão no cache (disponível por até 1 hora) para visualizar em qual etapa exata o fluxo foi interrompido e inspecionar os detalhes do alerta gerado.
Console de Gestão e Logs de Eventos

Exibe o histórico consolidado de execuções com o resultado das sessões, onde erros e falhas de runtime são sinalizados com destaques visuais para facilitar a análise de causa raiz pela equipe de operação.