Skip to main content
Verify the version tags to ensure you are consuming the intended content or, complete the latest version.

Error detection configuration

Error detection occurs when a connector is invoked by data pages. Connectors are used with data pages to read data — such as customer and insurance policy data — from an external system. Data pages are loaded on demand. All data source errors must be handled as part of the data page load mechanism. The type of data source that is leveraged to load the data page affects how errors are detected and handled. Connectors, report definitions, and lookups use the response data transform to detect errors. When data pages invoke a connector, the best practices are to:

  • Add error detection to all data pages
  • Invoke a reusable data transform to handle errors

Pega Platform™ provides a template data transform called pxErrorHandlingTemplate. This data can be used to create a reusable error handling data transform. The pxErrorHandlingTemplate data transform is in the base class and is shipped as part of the product. 

Each connector has an error handling flow. Pega Platform automatically invokes the error handler flow if the error is not detected by another mechanism.

Error handling data transform

The best practice is to use an error handling data transform if the errors are detected by using a response data transform in a data page. 

If the error is not detected on the data page, then the error handler flow for the connector is invoked to detect the error. The response data transform is invoked after the connector call is complete. If there is an issue, messages are added.

Response Data Transform Error Message

In your response data transform, use a when condition to check for any error messages on the page. If an error has occurred, apply the reusable error handling data transform.

Error handling flow

The error handling flow feature detects errors that are not detected in a data page. This feature is always enabled and allows you to implement a process for handling the error. It is typically used when the connector response is not required immediately — for example, when updating a legacy system.

Note: The error handler flow is not executed if the error is detected in the response data transform.

You can configure the error handler flow in the service tab for the connector.  By default, connectors use the standard ConnectionProblem flow. The flow can be copied and customized. You may also choose to create an alternative error handler flow.


When an error occurs, the original flow execution is paused. Control is handed over to the error handler flow. If the resource is unavailable, a transient error may be preventing processing. If there is no transient error, the connector is retried, and processing continues in a flow called FlowProblems.


The FlowProblems flow either routes the work item to a problem flow workbasket or notifies an operator about the issue. The operator may:

  • Retry the connector
  • Resume the flow without retrying the connector
  • Restart the initial flow
  • Cancel the error handling flow

Addressing responses from returned errors

If there is an immediate need for the response to be returned by the invoked service, you should:

  • Display an error message
  • Write the error to the log file

Writing a message to the log file helps troubleshoot errors. For example, a log file can be analyzed to identify patterns related to a specific error. In the log message, include details about the connector request to help identify the cause of the error.

Tip: In addition to writing the error to a log file, consider generating an email with details about the error to notify the system administrator or another interested party.

The template error handling data transform includes examples of calls to standard utility functions. You can configure the data transform to customize error handling behavior, such as providing more user-friendly error messages.

In the following image of the template error handling data transform, click the + icons to examine the sample utility function calls. 

Retry a connector invoked from a data page

If the returned error is temporary, you can give the user the option to retry the connector. To retry the connector, configure the data page refresh strategy:

  • Create a when condition that returns true when there are no error messages.
  • Set the Do not reload when setting so the data page does not reload if there are no error messages. 

Check your knowledge with the following interaction.

If you are having problems with your training, please review the Pega Academy Support FAQs.

Did you find this content helpful?

50% found this content useful

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega Academy has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice