Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Debugging DX API

Updated on August 5, 2022

Investigate your DX API that returns incorrect results to identify issues and correct the API behavior. Debugging is a critical tool for maintaining the good quality and health of your APIs.

You can debug your DX API on the server or the client side. Each method helps you to identify specific issues and correct specific errors.

The information contained in this article applies to both DX API Version 1 and Version 2.


When you encounter an error, you can find basic information about the error in the response body of your DX API. However, for security reasons, the response body provides only a general statement and error category, without additional information such as error codes, exception numbers, or where the error was encountered.

You can collect more details about the request and response of your DX API with the DebugPegaAPI system setting. When you set DebugPegaAPI to true, your system captures information about API errors in the PEGA log. The change is effective immediately.The setting is set to false by default.

The DebugPegaAPI system setting is particularly useful for debugging page instructions and field security errors, for example, when the request body of your DX API consists of fields that are not configured in the case, or when you try to update or remove a list element that does not exist.

The PEGA log contains warnings, errors, and information messages about internal operations and, with DebugPegaAPI set to true, collects the following information about errors and exceptions encountered by DX APIs:

  • Input values used in the request body of your DX APIs
  • Actions performed by your DX APIs
  • Fields in the view where your DX APIs encountered errors or exceptions
  • Descriptions of the cause for errors or exceptions
  • Error codes or exception numbers

For more information about opening and filtering logs, see Viewing logs.

By default, the PEGA log is filtered by your operator ID. When filtered by operator ID, the log shows only basic information for errors or exceptions of your DX APIs. To see more details, you need to use the overall view and use the search function.

The following log contains full details for a page instructions error:

(…) Processing Perform Assignment for input value : {“pageInstructions”:[{“pxObjClass”:”Code-MergeInstructions”,”listIndex”:”1”,”instruction”:”UPDATE”,”content”:”DELETE”,”content” (…)
(…) Applying UPDATE for .EmployeeList on the case.
(…) Applying DELETE for .EmployeeList on the case.
(…) API error for B-2: Pega_API_059: The Reference pyWorkPage.EmployeeList(5) is not valid. Accessing invalid index 5 whereas the list has 1 elements from Request (…)

To illustrate this error, an invalid request was sent in a controlled environment. The API is trying to update and delete an entry that does not exist.


Because the system logs details about the request body of your DX API, it is possible that the log contains Personal Identifiable Information (PII). To avoid security risks, change the DebugPegaAPI back to false after you finish debugging your DX API.Changing the system setting to false also helps with performance by preventing the log from overflowing.


You can inspect the request/response traffic of your DX APIs with the developer tools in your browser. The developer tools in your browser help you examine, edit, and debug the HTML, CSS, and JavaScript code on the page on which you run your application. With these tools, you can also inspect which assets the page requested and how long they loaded.

For more information, see Browser developer tools.

To debug the traffic of your DX API, open the Network section of the Developer Tools that lists the endpoints called by your DX API. From the list of endpoints, you can examine the following:

  • Headers, for example, to check if the cookie is invalid.
  • Requests, for example, to inspect what data your APIs send.
  • Responses, for example, to check if your APIs can access all necessary resources.
  • Stack trace, for example, to check active stack frames prior to an exception.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us