# Boas práticas para tratamento de erros em pipelines O tratamento adequado de erros é essencial para garantir a estabilidade, previsibilidade e confiabilidade das integrações construídas na Digibee Integration Platform. Sem uma gestão eficaz de falhas, os pipelines podem apresentar comportamentos inesperados, dificultando a manutenção e impactando processos críticos. Neste artigo, exploramos boas práticas para lidar com erros de forma eficiente. ## **Uso do Fail On Error e OnException** ### **Fail On Error** Essa opção está disponível nas configurações da maioria dos conectores da Plataforma. Quando ativada, a execução do pipeline é interrompida. Em conectores que utilizam [subfluxos](/documentation/developer-guide/pt-br/development-cycle/build-overview/pipelines/subpipelines.md), uma exceção é enviada para o fluxo do **OnException**. ### **OnException** O [**OnException**](/documentation/developer-guide/pt-br/development-cycle/build-overview/pipelines/subpipelines.md#onexception) está presente em alguns conectores com subfluxos, como [**Do While**](/documentation/connectors-and-triggers/pt-br/connectors/logic/do-while.md), [**For Each**](/documentation/connectors-and-triggers/pt-br/connectors/logic/for-each.md) e [**Retry**](/documentation/connectors-and-triggers/pt-br/connectors/logic/retry.md), e desempenha um papel importante na captura de falhas controladas. Ele permite centralizar o tratamento de erros em um ponto do pipeline, facilitando ajustes posteriores, análises e até novas inclusões no fluxo de erro, evitando a repetição da lógica ao longo do pipeline. ## **Resumo de erros em conectores de loop (For Each, Do While)** O **OnException** de conectores de loop, como o **For Each**, não interrompe a execução do loop. Isso permite compilar ou unificar todas as exceções que ocorrerem durante sua execução, possibilitando o tratamento após o término do loop. Mais informações estão disponíveis na [documentação oficial do **For Each**](/documentation/connectors-and-triggers/pt-br/connectors/logic/for-each.md). Uma prática recomendada é armazenar um resumo dos erros na memória do pipeline para exibição posterior, utilizando a cápsula **Add item to session (array)**. Essa cápsula insere os registros em um array chamado `resultList`, que pode ser recuperado posteriormente. É necessário incluir um objeto JSON no payload para adicionar corretamente um item ao array:
Caso a cápsula não esteja disponível, também é possível realizar essa ação diretamente no pipeline utilizando outros conectores, como o [**Session Management**](/documentation/connectors-and-triggers/pt-br/connectors/structured-data/session-management.md) e [**JSON Generator**](/documentation/connectors-and-triggers/pt-br/connectors/tools/json-generator.md)**:**
{% hint style="info" %} Essa abordagem deve ser usada com cautela, pois o consumo de memória aumenta conforme os registros são adicionados ao array. Em casos de grandes volumes de iteração, recomenda-se utilizar o [**Object Store**](/documentation/connectors-and-triggers/pt-br/connectors/structured-data/object-store.md) com o parâmetro **Isolated** ativado, por ser uma alternativa mais adequada. {% endhint %} ## **Revisão de timeouts de conectores de conexão externa em relação ao trigger** Ao configurar um pipeline, é fundamental considerar o tempo limite (**timeout**) dos conectores de conexão externa ([**REST**](/documentation/connectors-and-triggers/pt-br/connectors/web-protocols/rest-v2.md), [**DB**](/documentation/connectors-and-triggers/pt-br/connectors/structured-data/db-v2.md), [**SOAP**](/documentation/connectors-and-triggers/pt-br/connectors/web-protocols/soap-v3.md), [**MongoDB**](/documentation/connectors-and-triggers/pt-br/connectors/structured-data/mongodb.md)) em relação ao timeout definido no **trigger**. ### **Importância de alinhar os timeouts** O timeout do trigger deve ser maior do que a soma dos timeouts de todos os conectores externos. Isso garante que o pipeline tenha tempo suficiente para tratar possíveis falhas antes de ser encerrado. ### **Impacto dos tempos de resposta no pipeline** Se os conectores externos tiverem timeouts longos e o trigger tiver um valor inferior, o pipeline poderá ser finalizado antes da conclusão das requisições, gerando inconsistências e dificultando a identificação de erros. Por exemplo, se um pipeline tiver três conectores [**REST**](/documentation/connectors-and-triggers/pt-br/connectors/web-protocols/rest-v2.md), cada um com timeout de 30 segundos, o tempo total de execução pode chegar a **90 segundos**. Caso o trigger esteja configurado com um timeout inferior a esse valor, o pipeline será encerrado antes que os conectores finalizem suas execuções. ### **Dicas para configurar os valores de timeout** * **Calcule a soma dos timeouts** dos conectores externos e adicione uma margem de segurança ao timeout do trigger. * **Evite valores excessivamente altos**, pois isso pode comprometer o desempenho da plataforma. * **Considere os processos internos do pipeline**, como transformações e tratamento de erros, ao definir o timeout do trigger. * **Monitore regularmente o tempo de execução** dos conectores e ajuste os timeouts conforme necessário. ## **Validação de erros em pipelines com uso intensivo de Object Store** Quando um pipeline realiza múltiplas operações **CRUD** (Create, Read, Update, Delete) em uma coleção do [**Object Store**](/documentation/connectors-and-triggers/pt-br/connectors/structured-data/object-store.md), especialmente de forma simultânea entre diferentes fluxos, é fundamental seguir boas práticas para evitar inconsistências e falhas inesperadas. ### **Prevenção de erros em operações simultâneas** Considere as seguintes práticas: * Ativar a opção **Fail On Error** nos conectores que acessam o **Object Store**, para capturar falhas automaticamente. * Implementar validações após cada operação, usando os conectores [**Assert**](/documentation/connectors-and-triggers/pt-br/connectors/tools/assert-v2.md) ou [**Choice**](/documentation/connectors-and-triggers/pt-br/connectors/logic/choice.md), para garantir que os dados foram corretamente manipulados. * Monitorar acessos simultâneos ao **Object Store**, evitando sobrecarga e falhas por concorrência. ### **Exemplo de implementação** Se um pipeline realiza leitura no **Object Store** para, em seguida, atualizar os dados, um erro pode ocorrer caso outro processo modifique ou remova esses dados antes da atualização. Para mitigar esse risco, recomenda-se: * **Verificar os dados após a leitura**, garantindo que ainda estão disponíveis. * **Utilizar o conector** [**Assert**](/documentation/connectors-and-triggers/pt-br/connectors/tools/assert-v2.md) para validar a presença dos dados esperados. * **Aplicar o conector** [**Choice**](/documentation/connectors-and-triggers/pt-br/connectors/logic/choice.md) para definir rotas alternativas caso os dados tenham sido alterados ou removidos. Essas práticas ajudam a minimizar falhas e aumentam a confiabilidade nas interações com o **Object Store**. ## **Comportamento específico do conector Retry** O conector **Retry** possui regras próprias para o tratamento de erros, descritas [nesta documentação](/documentation/connectors-and-triggers/pt-br/connectors/logic/retry.md). É importante compreender o comportamento dos blocos **OnProcess** e **OnException** no contexto do **Retry**. Se o **OnProcess** contém um conector [**Throw Error**](/documentation/connectors-and-triggers/pt-br/connectors/tools/throw-error.md) ou está com o parâmetro **Fail On Error** ativado, e se o **OnException** também inclui um **Throw Error**, o Retry encerrará imediatamente suas tentativas, mesmo que ainda haja execuções pendentes. {% hint style="success" %} **Recomendação:** Para garantir que o **Retry** continue suas tentativas até atingir o limite configurado, evite usar o conector **Throw Error** no **OnException**. Assim, o pipeline poderá seguir com as execuções restantes antes de falhar completamente. {% endhint %} ## **"Redundância" de conexão no conector DB V2** Quando a string de conexão do conector [**DB V2**](/documentation/connectors-and-triggers/pt-br/connectors/structured-data/db-v2.md) inclui dois ou mais servidores, o timeout definido no campo **Custom Connection Properties** é aplicado individualmente a cada servidor. Por exemplo, com dois servidores e timeout de **30 segundos**: * A primeira tentativa utilizará **30 segundos** para conectar-se ao primeiro servidor. * Caso falhe, o conector tentará o segundo servidor, aplicando novamente **30 segundos**. ### **Gerenciamento das conexões ao banco de dados** O gerenciamento de conexões deve estar alinhado às necessidades do fluxo de integração. Configurações inadequadas podem resultar em: * **Excesso de conexões abertas**, afetando o desempenho do banco e do pipeline. * **Uso desnecessário de recursos**, comprometendo a escalabilidade e a estabilidade. ### **Recomendações para otimização** Revisar e ajustar os parâmetros de conexão pode melhorar o desempenho do pipeline e reduzir o impacto no banco de dados. Os principais parâmetros incluem: * **Pool Size By Actual Consumers** – Define o tamanho do pool com base no número de consumidores reais. * **Exclusive DB Pool** – Indica se o pipeline terá um pool exclusivo. * **Custom Pool** – Permite definir um pool personalizado. * **Keep Connection** – Mantém a conexão ativa entre execuções, o que pode impactar o uso de recursos. Para fluxos com alto volume de operações, revisar essas configurações é essencial para garantir performance e evitar sobrecarga. ## **Conclusão** A gestão adequada de erros na Digibee Integration Platform é essencial para garantir a estabilidade e a eficiência das integrações. Como vimos ao longo do artigo, é importante: * Configurar corretamente os conectores **Fail On Error** e **OnException**. * Entender os comportamentos específicos dos conectores **Retry** e **DB V2**. * Definir timeouts apropriados para conectores externos, alinhando-os com o trigger. * Adotar validações em fluxos concorrentes com **Object Store**, evitando inconsistências. A aplicação dessas boas práticas torna o pipeline mais resiliente, facilitando a detecção e resolução de problemas. Além disso, recomenda-se revisar periodicamente as configurações e estratégias de tratamento de erros, acompanhando a evolução dos processos de integração. Com uma abordagem estruturada, é possível garantir que as soluções desenvolvidas na Digibee sejam robustas, confiáveis e escaláveis. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digibee.com/documentation/resources/pt-br/best-practices/best-practices-for-error-handling-in-pipelines.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.