Generic error handling

Forms can present different user experiences depending on where a Flow fails and whether the user can correct the problem. The main tools are retry notifications and incomplete steps.

Error handling options

Option	Use when	Result
retry_notification	The user may be able to correct input and retry the Step	A dialog is shown with retry and restart options
incomplete	The Flow cannot continue or the failure should end the process	A configured incomplete Step is shown
summary	The Flow completed successfully	A configured summary Step is shown

Retry notification

Use retry_notification when a Step Pipe can fail in a way that the user may be able to correct. Typical examples include validation failures, missing data, or a business rule that should be explained before the user tries again.

The retry notification can show a generic message or map backend errors to specific translated messages.

{
  "retry_notification": "@include:retry-notification.json"
}

See Retry Notification for configuration details.

Incomplete Step

Use incomplete when the Flow should stop and show a controlled error page. This is useful when the failure is not something the user can fix directly, such as a missing backend dependency or a process state that prevents the Flow from continuing.

{
  "incomplete": "@include:incomplete.json"
}

See Incomplete step for configuration details.

Traceability

Error views can expose the request trace_id. This helps administrators and support staff connect the user-facing error with backend logs when troubleshooting.

When troubleshooting a failed Flow, start with:

• the visible error message
• the trace_id
• the Step where the error occurred
• the Step Pipe or Control Pipe that was running