SAP CPI

Tratamento de erro no CPI: passar não é aguentar

11 min de leitura · atualizado em setembro de 2026

Um iFlow importa no CPI, roda com o payload de teste e entrega a mensagem no destino. Isso significa que ele funciona. Não significa que ele aguenta — aguentar é o que acontece quando o payload chega vazio, quando o destino devolve 503, quando um campo opcional some, quando o certificado vence numa terça-feira às três da manhã.

A distância entre os dois estados quase sempre está em quatro decisões de tratamento de erro. Nenhuma delas é difícil. Todas costumam ficar para depois.

1. O `catch` que faz a mensagem desaparecer

Este é o mais comum e o mais caro. Um script Groovy dentro do fluxo captura a exceção para “não derrubar o processamento” e segue adiante:

try {
    def json = new JsonSlurper().parseText(body)
    total = json.items.sum { it.price * it.quantity }
} catch (Exception e) {
    total = 0     // segue o baile
}

O fluxo termina com sucesso. O MPL mostra verde. E o pedido foi para o Salesforce com valor total zero.

O erro aqui não é usar try/catch — é usá-lo para esconder. Capturar é legítimo quando existe uma decisão real sobre o que fazer com a falha; quando a única coisa que o bloco faz é evitar que a exceção suba, ele não está tratando o erro, está apagando a evidência dele.

A forma que aguenta registra e devolve a exceção:

try {
    def json = new JsonSlurper().parseText(body)
    def items = json?.items
    if (!items) {
        message.setProperty("OrderTotalWarning", "payload sem itens")
    }
    total = items ? items.sum { (it?.price ?: 0) * (it?.quantity ?: 0) } : 0
} catch (Exception e) {
    // Visível no MPL, e a mensagem continua marcada como falha
    message.setProperty("ErrorMessage", "processData falhou: ${e.message}")
    throw new IllegalArgumentException("Falha ao converter payload JSON", e)
}

Três mudanças, todas pequenas: a navegação segura (?.) impede que um campo ausente vire NullPointerException; o aviso em property deixa rastro mesmo no caminho sem erro; e o throw preserva o comportamento do CPI — a mensagem é marcada como falha e o subprocesso de exceção dispara.

Regra Capturar sem relançar só é aceitável quando o fluxo tem um caminho alternativo definido para aquele caso. Se não tem, o catch está trocando um incidente visível hoje por um dado errado descoberto em três semanas.

2. Exception Subprocess não é opcional

Um iFlow sem Exception Subprocess entrega o erro cru ao chamador — ou, pior, simplesmente encerra. Com ele, você decide o que acontece: registrar o contexto, devolver um código HTTP acordado, persistir a mensagem para reprocessamento, notificar.

Um detalhe que passa despercebido: o subprocesso precisa terminar em um Error End Event, não num End Event comum. Terminando normal, o CPI considera que o erro foi tratado com sucesso e a mensagem aparece como completed no monitor. Você ganhou o tratamento e perdeu o registro da falha — de novo a mensagem verde que mente.

3. Retry que não esconde a causa

“Três tentativas com cinco minutos de intervalo” resolve a falha transitória: um 503 momentâneo, um timeout de rede, um token que expirou meio segundo antes. Serve para isso, e só para isso.

O problema aparece quando o retry vira a resposta para qualquer erro. Um 401 por credencial errada não melhora na terceira tentativa; um payload malformado também não. O que o retry faz nesses casos é atrasar o diagnóstico e multiplicar a carga no destino.

Na prática: repita apenas erros que podem se resolver sozinhos (5xx, timeout, falha de conexão) e falhe rápido nos demais (4xx de autenticação, de contrato, de validação). E defina explicitamente o que acontece quando as tentativas acabam — devolver erro ao chamador, persistir em Data Store ou mandar para fila morta são decisões diferentes, com consequências operacionais diferentes.

4. Log que serve para depurar, não para encher

O MPL aceita anexos, e é isso que transforma um erro em algo diagnosticável: o payload que entrou, o payload que saiu depois da transformação, os headers relevantes. Sem isso, o que sobra no incidente é a mensagem de exceção — e a mensagem de exceção quase nunca explica qual dado causou a falha.

Três cuidados fazem a diferença entre log útil e log que ninguém lê:

Registre em pontos de fronteira, não em cada step: o que chegou, o que saiu de cada transformação relevante, o que foi enviado.
Não registre o que não pode vazar. Anexo de MPL fica acessível para quem tem acesso ao monitor. Dados pessoais e credenciais não entram — e essa decisão precisa ser tomada no desenho, não na auditoria.
Propague um header de correlação. Sem ele, rastrear uma transação que passa por três iFlows vira arqueologia por horário.

E o próprio log precisa ser defensivo: o messageLogFactory é injetado pelo runtime do CPI, mas em cenários de simulação ou com o trace desligado o objeto pode não estar disponível. Um script de log que derruba o fluxo porque o log falhou é uma ironia cara.

def messageLog = messageLogFactory?.getMessageLog(message)
if (messageLog != null) {
    messageLog.addAttachmentAsString("PayloadEntrada", body ?: "", "text/plain")
}

A conta que ninguém faz

Cada um desses quatro itens custa entre dez minutos e uma hora de trabalho no momento da construção. Nenhum deles aparece no teste de aceite, porque o teste de aceite usa o payload feliz. E todos aparecem no primeiro incidente de produção — quando o custo já não é medido em horas de desenvolvimento, mas em horas de indisponibilidade e em dado que precisa ser reconciliado à mão.

É por isso que vale medir qualidade de iFlow antes do import, e não depois do incidente. As perguntas são objetivas e cabem numa lista:

O sender exige autenticação?
Existe Exception Subprocess, e ele termina em Error End Event?
Há política de retry declarada, e o que acontece quando ela se esgota?
Há log em pontos de fronteira, sem dado sensível?
O header de correlação é propagado?
Os timeouts dos adapters estão explícitos?
Os scripts tratam campo ausente sem derrubar o fluxo?

Onde isso encosta no que construímos

O validador de iFlow do iFlowMind responde a essas perguntas lendo o ZIP do pacote: dá uma nota de 0 a 100 por eixo — segurança, tratamento de erro, observabilidade, performance, boas práticas — e lista os achados por severidade, antes de o pacote entrar no CPI.

Vale uma confissão: quando passamos pelo validador um pacote gerado pela nossa própria ferramenta, a nota foi 75 de 100, com um achado crítico — sender sem autenticação. É exatamente o comportamento que se espera de um validador que serve para alguma coisa. Uma ferramenta que aprova o que ela mesma produz não está medindo nada.