Skip to Content
Author's profile photo Laura Johannhörster

PI REST-Adapter – Error-handling

Hello everybody,

with modern REST API we are facing the situation to handle different error types that we have to translate in a format the user can understand, espacially if we have a synchronous scenario.

In this example, we would like to perform a GET call to a REST API and catch all errors different to HTTP code 200 (which means OK). This is very generic error handling, but should be used as an easy example to understand the mechanism.


I create different message types for request and response. Here you can see the response message type:


As response structure, we create additionally to the normal fields an optional error structure. This structure will only be filled by REST adapter, if HTTP response is unequal 200.


Then I create a 1:1 message mapping for the“ request“ and the „response“.

But there is a special feature in the „response“ mapping. I created a UDF:


The UDF is used to generate an error message if an error occurs. So the message will visible as error in PIMON and the message is canceled. This UDF does not necessarily have to be used. It only serves as a feature.

The Argument „var1“ is only used as input for the UDF and will not be used.

The mapping for the field „errors“ looks like this:


Because I want to have a more informative error message in the PImon I configured an error handling in the REST adapter.

The expression „http_result“ is only entered in error handling.


There are the following additional expressions, which can be entered here:

from website:


Before the error-handling was inserted, the following error message appear in PIMON:


After configuration of the error-handling I get the following error message in PImon:


This error message is more meaningful than if I did not enter the error handling.


You could also add a receiver determination to check if the error structure exists and add an additional receiver e.g. to send an error alert via E-mail.


I hope this blog is helpul to understand.


Thank you,


Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Michelle Crapo
      Michelle Crapo

      It was great!

      So if you have a message number that is not defined - it will show up as the message sent from the API?

      I'm assuming you are only coding for the common errors?

      Thank you,


      Author's profile photo Christian Breitsprecher
      Christian Breitsprecher

      Good Blog.. that error treatment looks familiar. 😉

      Author's profile photo Philippe Addor
      Philippe Addor

      Laura, as far as I see on the screenshot, the exception happens because the adapter seems to expect JSON (because you probably configured JSON under “Response Format”) but since you input XML (the custom message content configured for non-200 responses) it leads to an exception.  So the response mapping actually never gets triggered.

      This means, that the sender would not get the error message back but probably a 500 Server Error from PO (you write that you wanted to  "translate [the error] in a format the user can understand, espacially if we have a synchronous scenario.". I think in order to make it work you would need to set the response format in the receiver channel to XML. But I didn’t test it.

      If you want to display the error in the message log (PIMon) and not return it to the sender, as you actually showed above, it seems to be a possible way to make it fail due to wrong response format, as a side-effect, so to say. 


      Author's profile photo RAJIB BALIDA

      Hi Philippe,

      Your suggestion did not work. Kindly suggest any other way as i have been facing exactly the same issue. Need to send response back to source system in case of target system server down (HTTP 503). However, message has been getting cancelled.

      Author's profile photo RAJIB BALIDA

      Laura Johannhörster,

      Please let me know the steps you did follow to overcome from this issue.