Reference
Understanding handled & unhandled experience failures in Pendula

Experience lifecycle: errored and failed experiences

Errored experiences

If there's an issue where a flow designer can make a change that will affect in-progress experiences after making a change outside of Pendula and then retrying, the flow will transition to an error state, and pause all experiences. Learn more about managing flow errors here.

Common scenarios that lead to errored experiences:

• Incorrect or missing credentials in integration actions
• Missing required data fields in payloads sent to downstream systems
• Invalid merge field references or formula errors

The platform treats these differently because they require different approaches to troubleshooting and resolution.

Failed experiences

If there is an issue in the set-up or configuration of a flow that cannot be fixed once the experience has started, the experience will return a failure outcome. The individual experience will either end, or follow the failure outcome path, but it does not affect other experiences.

Common scenarios that lead to failed experiences:

• Email bounces
• SMS delivery failures
• Web request 4xx responses
• Integrations missing data from merge fields, or unexpected values

Failed experiences: ‘handled’ and ‘unhandled’ experiences

When experiences progress through your Pendula flows, they may encounter issues that can stop their progression. Understanding the difference between handled and unhandled failures is useful for building resilient customer journeys and effective troubleshooting.

Handled failures

Handled failures occur when an experience encounters an issue, but the flow designer has configured outcome paths to manage these situations. When outcome paths are enabled, experiences can continue through alternative routes rather than ending abruptly.

Example: An email bounces due to an invalid recipient address, but you've enabled the 'Rejected' outcome path to automatically send an SMS as a fallback channel.

Unhandled failures

Unhandled failures occur when an experience encounters an issue and no outcome paths have been configured to manage the situation. These experiences end with a 'Failed' status.

Example: An email bounces due to an invalid recipient address, but no 'Rejected' outcome path is enabled, causing the experience to terminate.

Flow examples: handled and unhandled failures

In the below example, we have configured a flow with an email action and a failure path. If the email fails to send, the experience will continue down this path to the conversation node. For the conversation node, we have not configured any failure fallbacks.

You can also see that the activity summary shows 1 complete experience and 1 failed experience.

Example 1: Complete experience with a handled failure outcome

For the first experience, the webhook trigger has sent through an invalid email address, and the message has failed with the reason of Fail to deliver (listed under the Message failed activity).

The experience has been marked as Complete because it followed the handled outcome and behaved as expected for a failure path, continuing on to the conversation fallback sequence.

You can check the address that was received by the trigger (and other details of the email message) under the Message queued activity.

Example 2: Failed experience with an unhandled failure outcome

For the second experience, the webhook trigger sent both an invalid email address and an invalid phone number for the conversation fallback. The experience will finish on the conversation node as shown by the failure icon, and also show the failure as Failure/failed normalisation, along with the timestamp.

For a more specific failure message, jump to the Message validation failed activity and view the failure message for the validation, which in this case explains that the Receipient must be a valid phone number, got: .

Again, you can review what was sent under the Message queued activity for further detail, and see the phone number was blank.

How to configure outcome paths

To transform unhandled failures into handled ones, you need to configure outcome paths using the 'Outcomes' tab in each node's settings modal:

1. Open the node settings by clicking on any node in your flow
2. Navigate to the 'Outcomes' tab in the settings modal
3. Enable the appropriate paths by toggling the path switch for scenarios like 'Rejected', 'Not sent', 'Failed', or 'No reply'
4. Configure wait times where applicable (e.g., for email delivery confirmation)
5. Connect the outcome paths to subsequent nodes that handle the failure scenario

Implementing fallback strategies

Once outcome paths are enabled via the Outcomes tab, you can implement various fallback strategies:

Common fallback approaches

• Alternative channels: Switch to SMS or WhatsApp when email fails
• Segmented strategy: Apply different fallbacks based on specific failure reasons
• Manual intervention: Create tasks or notifications in support CRM systems for human follow-up and monitoring
• Multi-tier fallbacks: Switch to another channel when a message fails to reach the recipient on the current channel

Best practices for handling failures in your flows

1. Always review the Outcomes tab when configuring communication nodes to identify available fallback paths
2. Enable outcome paths proactively rather than reactively after experiencing failed experiences
3. Configure appropriate wait times in the Outcomes tab to accommodate soft bounces and temporary delivery issues
4. Use merge fields from outcome data to create sophisticated routing based on specific failure reasons
5. Test your fallback paths to ensure they work as expected before activating flows