Skip to Content
Technical Articles

PI REST Adapter – Custom error handling

This blog is part of a collection of blog entries that shows architectural concepts and configuration of the SAP PI REST Adapter. We also added some sample scenarios to make it easier for you to understand how your scenario can be implemented using the PI REST Adapter.

If you haven’t done so far, best is to start with the very first blog PI Rest Adapter – Don’t be afraid within the blog series covering the concepts of the REST adapter. A complete list of all blog entries can be accessed from here PI REST Adapter – Blog Overview.

With release 7.31 SP15 / 7.4 SP10 we have enhanced the REST adapter supporting custom error handling. You can maintain rules for defining how the message processing should behave in certain (error) situations. For instance, you would like to ignore particular error codes, or you would like to reply with a custom message based on message content, etc. In this blog, I would like to show you the various options that you have when defining custom error handling.

From release 7.31 SP17 / 7.4 SP12 / 7.5 SP01 onwards, the custom error handling has been further enhanced in a way that situations where no errors occur can be handled. The following features have been introduced:

  • A new rule type Always
  • A new flag to inverse the rule expression
  • A new rule type checking if a message is empty
  • New variables keeping http attributes which can be used in custom message

Scenario 1 – Custom error handling on receiver side

I would like to introduce the various custom error handling options that are supported based on the REST receiver adapter. I have configured an Integration Flow from SOAP to REST which calls the REST endpoint exposed by the scenario from one of the previous blogs PI REST Adapter – Exposing a function module as RESTful service. Using the custom error handling on the REST sender side of this scenario, I am able to mock various error situations. This way, I am able to show you the behavior of the particular error situations by comparing when calling the RESTful service using either the Advanced REST Client Application in Google Chrome browser or via the additional SOAP to REST Integration Flow.

01 iflow.png

For each of the options, let’s take a closer look at how the receiver channel of adapter type REST has been maintained.

Custom error handling options

Double-click on the receiver channel of type REST, and switch to the Error Handling tab below the Adapter-Specific tab. Here, you can define rules that are validated during runtime. For each rule you have to define a condition and an action. The condition usually consists of a source and a value, the action can be either raising an error, ignoring the error, or replying with a custom message.

Fetch various http error situations and reply with respective custom message

We would like to return a custom text depending on particular error situations of the http transport layer. I have defined two rules as follows:

  • Reply with custom text <error>not found</error> if HTTP Status Text of the service call response contains the phrase Not Found
  • Reply with custom text <error>server not reachable</error> if HTTP Status Code equals either 500 or 503

In any case, the HTTP request becomes successful, i.e., the http status code is set to 200.

02 Source is error - channel.png

Let’s run the scenario that leads to an http status code 500. When directly calling the REST service using the Advanced REST Client, we get an http status code 500 – Internal Server Error.

05 customer 21.png

When calling the REST service via the SOAP to REST Integration Flow using soapUI, the http status code 500 is fetched by the rule and the respective custom message is returned.

12 soapui customer 21.png

In the message monitor, you can see that the message has been successfully processed. An audit log entry has been added showing the rule which has been applied and the action taken.

20 message moni customer 21.png

Reply with custom message in case of a runtime exception

We would like to return a custom text whenever an exception within the REST adapter occurs. In our example, the RESTful service returns an invalid JSON format so that the conversion from JSON to XML fails. I have defined the rule as follows: Reply with custom text <error>a validation error occured</error> for source Exception.

33 validation error configuration.png

If we call the RESTful service without having defined the rule, the message goes into a system error status. From the audit log in the message monitoring, you can see that an error validating the JSON input occured.

30 validation error.png

If we call the RESTful service with having the rule above active, the message will be delivered succesfully with the custom message as response. From the audit log you can see that the respective rule has been applied.

32 validation error fetched in message moni.png

Reply with custom message for a particular JSON element

If the resource, here the customer, does not exist in the backend system, the field name in the response of the service call is set to NONE. We would like to return a custom text if the value of the JSON element name equals NONE. So, as source we choose JSON Expression from the drop down menu. The rule is met if the JSON Element matches the expression NONE. As action we choose Custom Result. Within the message content we use a variable in curly brackets which is replaced by the id of the customer during runtime.

03 Source is JSON.png

When calling the REST service using the Advanced REST Client, the response in JSON format contains an element name equals NONE.

11 customer 76.png

When calling the REST service via the soapUI, the respective custom message has been returned with the id derived from the request url, here 76.

21 soapui customer 76.png

Raise an error for a particular header element value

The response should be in JSON format. If an XML is returned, an error should be raised. So, we create a rule with source HTTP Header Element checking if the http header element content-type contains the term application/xml. If the rule matches, the action should be to raise an error.

03 Source is Header Element.png

When calling the REST service using the Advanced REST Client, you can see that the response is in XML format instead of JSON, and the header element content-type is application/xml instead of application/json.

26 chrome content type xml.png

When calling the REST service via the soapUI, from the audit log in the message monitor you can see that the respective rule matches, and the message is put into an error status.
26 message moni content type xml.png

Ignore error for a particular text in payload of response

In case of any timeout when calling the REST service, we would like to ignore the error. Here, we parse the payload of the response searching for the term Timeout. So, as source we choose Text Content from the drop down menu, and maintain *Timeout* as expression. As action, we select Ignore Error from the drop down menu.

28 config timeout.png

When calling the REST service using the Advanced REST Client, we get an http status code 504 – Gateway Timeout. In the response payload, the reason is stated as Timeout.

29 chrome timeout.png

When calling the REST service via the soapUI, from the audit log in the message monitor you can see that the respective rule applied, and the message is put into status Delivered.

27 message moni timeout.png

Note: The following three scenarios are supported from release 7.31 SP17 / 7.4 SP12 / 7.5 SP01 onwards only.


Reply with custom message if response is empty

If you choose Text Content as Source, you have the option to define an action if the http result is empty. Here, select the flag Result message is empty.

01 Config.png

Reply with custom message in case of any error

We would like to reply with a custom message whenever the http status code is not 200. The custom message should provide information about the issue of the RESTful call. Define a rule with Source HTTP Status Code, select the flag Selection does NOT match, and maintain Status Code 200. As Action choose Custom Result. In the Message Content you can use the variables http_status and http_status_text in curly brackets.

01a Config.png

In case of an http status code 500, the rule applies and the respective http status code and text is displayed.

2-18-2016 4-53-26 PM.png

Always ignore errors

In case that any errors should be ignored, you can define a rule with Source Always, and Action Ignore Error.

01 Config.png

Scenario 2 – Custom error handling on sender side

Always send an http status code 202

The following scenario is supported from release 7.31 SP17 / 7.4 SP12 / 7.5 SP01 onwards.

Instead of sending an http status code 200, you would like to send the status code 202. So, create a rule on the REST sender adapter with Source Always, Action Custom Result, and HTTP Status Code equals 202. By selecting the Use Message Payload flag you ensure that your response message is kept.

01 Config.png

When calling the RESTful service from the Advanced REST Client Application in Chrome browser, you can see that the http status code has been set to 202.

02a Chrome.png

I hope this blog was helpful to understand how the custom error handling can be used. If you like to learn more, check out the other blogs in the series, accessible from the main blog PI REST Adapter – Blog Overview.

You must be Logged on to comment or reply to a post.
  • Hello Alexander,

    First of all, thank you for the article, I believe it explains neatly and in good detail the options we have to configure the custom error handling for the REST adapter.

    I have a question regarding the Ignore error rule, particular to an scenario we are working with.

    We are trying to handle an HTTP 500 error, that comes along with  the following response body


        "errorCode": 120322,

        "errorMessage": "(120322) Error description"


    We are trying to handle this response body, so we opted to use the ignore error configuration. Therefore the error is being ignored, but we are getting an empty payload for the response:


    I would appreciate if you could point me with some hints on the feasibility of this scenario,

    Thank you in Advance,


    • Hi Edgar,

      in the ignore error case, the payload is empty since we never know what is returned by the provider in an error case. Would you expect to keep the payload? What about having a flag where you can either remove or keep the payload of the response?


      • Hello Alexander,

        Thank you for your response, in this case we would be intending to keep the payload, since we can find a more detailed error there. A flag like that would be great, I wonder if there is an approach we could follow to implement it or if this is an option that could be added to the adapter, and if that is the case, please let us know if there is anything we could do to collaborate.

        Thank you again,

        Best Regards!


  • Hi Alex,

    As others have expressed, Can you please tell us, How to preserve the REST response when HTTP response code is non 200.

    Currently REST receiver adapter seems to ignore the response for non 200 HTTP response code.


  • Hello again Alexander,

    Thank you very much for including the error handling functionality, we are looking forward to November 🙂

    I also have another inquiry, not sure if this would be the right place, but we are trying to manage a JSON array for the response ( response beginning with "[" instead of "{" ).

    We saw a possible answer on this scn post:

    JSON to XML conversion in receiver REST communication channel

    However, we are wondering if there is any plan to support this scenario as a standard adapter scenario.

    Anyway, thank you very much again,

    I hope you have a great day,

    Best Regards !


      • Hi Alex,

        That's good news, thank you for the bugfix!

        We stumbled upon another issue which happens when we have a REST receiver that expects an array in the JSON:

        In the XML schema we model those elements as 1:n. The conversion to JSON arrays works fine as long as we have at least two occurences of the element. If we only have one occurence, the XML to JSON conversion will produce {element":"X"} instead of {element":["X"]}.

        As the receivers expect an array in JSON, no matter if the occurence is 1 or n, this is causing serious trouble for us. Currently we are integrating two independent partners via REST and with both we are facing the same issue.

        Is there a fix for this already (I haven't found a note yet)?

  • Hi,

    We also need REST adapter to handle JSON array appropriately. Hope SAP fixes these basic issues in the next releases. REST and JSON are becoming defacto standards in exposing backend functionality as webservice. This will be a big selling point for SAP.


  • Hi Alexander,

    This is really nice and informative blog. Thanks for sharing this.

    I have a question regarding the error handling. We are configuring integration with REST web-services using REST adapter with SAP PI 7.31 (SP15).  Whenever are getting errors pertaining to data we are getting HTTP 500 error in SAP PI and no other information about error. However, if I call the Web-Service using Postman with same payload, it gives the error code as 500. Also, it provides the error text saying that which field was having issue.

    Rest WS Error.jpg

    Can we catch this error message anyhow in SAP PI and send it back to source system?



    Rest WS Error.jpg
      • Hi Alexander,

        Thank you for the blog. I have followed most of your blogs on REST adapter, they all are such nicely explained that I was able to test all of them successfully.

        I have a small doubt, how should we map the response body of the REST receiver service to sender?

        I am trying a scenario with SYNC SOAP sender and REST receiver. Everything is working except that I am not able to map the REST response back to my SOAP sender.



  • Hi Alex,

    Is this feature (Processing actual HTTP response body when response code is not 200) implemented in 7.31 SP17 . We have installed  7.31 SP17 and does seem to see any option on the receiver REST adapter to handle HTTP response when HTTP response code in not 200.

    Please clarify.



  • Hi,

    We are on 7.4 SP13 and have a synchronous SOAP/XI to REST scenario. Is it possible to generate a fault message out of an errornous response? The fault message should include the {http_result}.

    We've tried to assign the sender and receiver interface fault messages and mapped them within the operation mapping. In the REST receiver channel we have added a custom result for all non HTTP 200 responses which creates a fault structure with the {http_result} within. Unfortunately this does not trigger the fault mapping, but is failing on the message mapping of the standard response.

    Also trying to do an interface split out of the standard response mapping did not trigger an exception / fault message. Instead we have a response that looks like a fault message but is not triggering the exception / fault behaviour for the sender (BPM).

    Is there any other way to create a fault message containing body information in case of a non HTTP200 response? Ideally we would be able to trigger an error instead of custom result and have the possibility to include the {http_result} in the error message.

      • Hi Alexander,

        Thank you for wonderful series of blogs on REST.

        We are on PO 7.5 SP06 and trying to get the non-200 response back to sender sysetem. Success message is coming to mapping and to source system. But for 400 Bad request, we are not getting ADAPTER exception with an error "premature end of file" in the log.

        However, we are able to workaround as mentioned in comment to map {http_result} to source field. But, we are looking a standard way to get the error code and text as it is from REST POST operation and send it back to Sender application. Please suggest.


    • Hello Christian,

      The fault mapping is not triggered because the REST adapter sets the message class for the generated XI response messages for non-200 HTTP calls either to Application or ApplicationResponse and not to ApplicationError.

      The issue is fixed with SAP Note 2273265.

      Best regards,


      • Hi Dimitar,

        We have tried out the note but it doesn't seem to make a difference.

        I am not sure if we are using the correct procedure:

        We have assigned a fault message to both service interfaces and created the message mapping + assigned it for fault in the operation mapping.

        In the REST receiver channel we are using the setting "Selection does NOT match HTTP code 200 -> Action = custom result -> Message Content = <ns0:FaultMessage ...." within the fault message we are using {http_result}.

        When we now receive back an HTTP 401 for example, the message mapping for the fault message is not triggered. Instead the message mapping for the normal response message is being triggered and fails as the input is is not the expected response, but the FAULT structure that we are generating in the REST receiver channel.

        Is this the correct procedure?

        When we use Action = Error instead, we receive an Exception (System FAULT) but are not able to see/include any information of the {http_result}.

        • If anyone is facing the same issue:

          Our current workaround is to add an optional field "error" to the response message structure of the sender which is filled with the {http_result} in the REST receiver adapter.

          The setting in the REST adapter error tab is: source = exception, action = custom result.

          The fault message from the receiver interface has been removed. Inside the message mapping of the response we check the content of the new error field. If it is filled, we throw a runtime exception in a UDF and pass the {http_result}.

        • Hello Christian,

          As mentioned in SAP Note 2273265 - in your case the module parameter "setAppErrorOnCustomMessage" has to be set on true in order the message class of the response message to ApplicationError. This should be able to trigger the Fault mapping.

          Your workaround is suitable but nevertheless REST adapter message class behavior about messages generated with custom error handling is not deterministinc as it  is not clear if in this case the call is treated as successful or not. With his additional module parameter it is possible to tune this behavior to the desired one.

          Best regards,


  • Hi Alex and Dimitar,

    We are on Netweaver 7.4 SP 12, However We are still not able to download 7.4 SP 13 with new REST Adapter feature (REST adpter non 200 response processing) . Can you please tell me when this would be available to downlaod?



  • Hi Alex,

    what will happen if target is not returning any of the values.

    I am getting error like "http_result is not configured, or has an empty value "

    may adapter module can pass empty if this is not coming from target...

    • Hello Muni,

      The issue with unavailability of the http_result internal variable is solved by SAP Note

      2273265 "Problem acessing error response message with internal variable and wrong message type for the generated XI message"

      Best reagrds,


      • Hi Dimitar,

        my PI system is already in 7.4 sp13.

        i am able to use http_result variable, and it gets filled when text is returned by target. this text comes for some status codes but not for all i guess.

        I dont remember the status code for which http_result is not getting filled. if it is empty, you can return empty string in the adapter module. so that one generic error handling(200 does not match) will suffice all status code error handling.

  • Hi Alex/Dimitar,

    I have configured a REST sender adapter with Dynamic attributes (REST ID (id)) with pattern Element as {userID}.

    In the same REST sender adapter, I have configured Custom Error handling option and trying to refer {userID} in the message content as

    <data>User ID {userID} not found</data>

    However in the actual response, value of {userID} is not getting substituted. Can you please suggest what could be wrong here?

    <data>User ID {userID} not found</data>



  • Hi Alexander
    Nice Blog!
    In the last days Ihad my first experiences in using "custom error handling" and for me this blog was an great infomation pool.
    In general I was succesfull in handling custom errors in a receiver channel - but now I 've got a question:

    Where can I find an overview of usable predefined variables (like http_status or http_status_text). I would like to use values of a response header field in custom result message content - is there a variable to achieve this?


    • Hi Edgar,

      see Custom Error Handling - Advanced Adapter Engine - SAP Library

      According to the documentation, only the 3 variables  http_status, http_status_text, and http_result are supported. Although you can use dynamic attributes in the custom error text, on the receiver channel the dynamic attributes refer to the original request message. so this wouldn't help you here.

      In Configuring the Receiver REST Adapter - Advanced Adapter Engine - SAP Library it is mentioned that the HTTP headers of the HTTP result message are copied into the XI message as dynamic message attributes and are therefore available for later reference. So the only option I see is that you create your custom error message within a mapping of your response, here you can then use the dynamic attributes


      • Hi Alex
        thanks for quick response.
        I tried before to use headers of response message as dynamic attributes. But it's never so easy as it looks like 🙂
        I need the value of the header parameter "location", which is used for redirecting (with HTTP302 response code).
        I set module parameter ProceedRedirect to false - so the message isn't redirected.  Now I can see header parameters as dynamic attríbutes in dynamic configuration view. All except one - the "location" header is missing 🙁
        So I tried custom error handling to keep this parameter - but how to get it?
        It' s a really challenging issue ...

        But nevertheless thanks for your support and this blog!


  • Hi Alex,

    I am trying to use {message_result} variable for Sender Rest Channel custom error handling( In case of any error on receiver side). There is not much info how to use it, I thought it would be same as {http_result} but it is not working.

    SAP_XIAF version is :


    Also: Sap Note 2175250 - New Feature: Enhancements in custom error handling

    Is there any way to get this working?



  • Hi Alex,

    For me also same problem,  {message_result} not working in sender channel, this is sender async channel. And the variables   http_status and http_status_text in curly brackets not working. I too updated the Sap Note 2175250, but still not working.
    What  will be problem?


  • hello,

    my receiver REST channel is not waiting for 200 response from legacy end point. How to wait  or get confirmation 200 ok from endpoint.
    with out this 200 message my message gets Delivered status.


  • Hi Alex,

    Thank you so much for the detailed write-up...  I am also looking into how to capture the entire return message from a REST call and have it be recorded so it can be sent via email when an <error> tag is present.  I have tried using:

    Source:  Text Content

    Expression (Glob):  *<error>*

    Action:  Custom Result

    Message Content:  {text_content}


    Is {text_content} a valid variable that can be used to capture the entire results returned from the REST call?


    Thank you,


  • Hi Alexander,

    Have you ever been introduced to this case?

    Any help would be grateful.



  • Dear Experts,

    We have Synchronous scenario that is consuming the REST Service(POST). During the POST the following exception is raised. The REST service when tested stand alone works for same data . Is there any spefific setting we are missing ?

    We are following the for consuming the sync service in SDN . Custom event handling: Error. Rule: 1 Exception

  • Hi Alex,


    We have a scenario where we are running REST-adapter to REST-adapter to expose a REST-service to a consumer system. I have a problem with the error handling where we want to respond with the error json payload from the receiver system as well as with the same HTTP Status code we get from the receiver system.

    In the REST receiver adapter I am able to catch the error http status codes and set message content to {http_result}.

    If I don't do any error handling on REST Sender-side PI will respond with HTTP 200 OK and the json error payload from receiver system. However, if I want PI to also respond with the same HTTP status code as we get from the receiver system I'm unable to do that.

    On the REST Sender side I try to catch the errors from receiver side by looking at the json payload:

    "timestamp": "2017-10-31T10:23:28.274+0000",
    "status": 400,
    "error": "Bad Request",
    "exception": "org.springframework.http.converter.HttpMessageNotReadableException",
    "message": "JSON parse error: Unrecognized token 'hej': was expecting ('true', 'false' or 'null'); nested exception is com.fasterxml.jackson.core.JsonParseException: Unrecognized token 'hej': was expecting ('true', 'false' or 'null')\n at [Source:; line: 1, column: 7]"

    But I am unable to also pass the http_result.:

    The response to sender system will now be HTTP 400 but with a payload of "{http_result}". Do you have any suggestions on how I can pass the http_result from REST receiver to REST sender adapter?


    Best regards,


    • Hi Oscar,

      Did you find any solution for the above? I have the same requirement (REST to REST Scenario and error message need to send to sender REST in a fixed JSON format)  but unable to achieve.





      • Hello Prem,


        solved it by using the first solution I posted with just catching the HTTP error codes on receiver side and fetching {http_result}. With no error handling on sender side PI will respond with the caught JSON-payload and HTTP200. Sender system was OK with HTTP200 as long as they got the error payload.


        I did not find a solution to keeping the error JSON-payload and responding with the correct error HTTP status code.

    • Hi Oscar,

      Did you find a solution that allows for transferring both the http response code and a the payload?

      If SAP had put the “{http_result}" in the ASMA dynamic configuration and made it possible to use ASMA on the "Error handling" tab on the sender adapter "result handler" source field the problem would be solved and even better woulde be to be able to set the http status code from ASMA.

      Regards /O



  • Hi Alex,


    I have an asynch scenario.

    The backend returns http code 500 with reason text “system error”.

    The payload contains more information about the error but the rest adapter throws the payload away so it isn’t possible to view it.

    This note should solve the problem but isn’t working.

    result handler is set to “—unused—”

    setting parameter “useResponseErrorMessage” = true
    results in that the message is processed successfully and the error is ignored (not what is expected)

    How can you make the adapter log the response payload on error?


    For asynch scenario you would like to inspect the payload so it contains the excpected content. This is important as sometimes you may get a redirect to a web page to change password and the change password page returns http code 200 even though the message wasn't processed on the receiver side. PO however marks the messages as successful due to the http 200 even though the message isn't processed on the receiver side. 




  • Hi Alex,

    I'm using the rest sender adapter tab "Error Handling"

    I need 12 "Result Handler":s. It's limied to 10 in the gui.

    Is there any plan to fix this to unlimited number of result handlers?



  • When we have a REST sender with QOS = EO, is it possible to make it return HTTP 200 instead of HTTP 202? When trying to configure it similar to the the blog post (where 202 is returned instead of 200 for QOS = BE), it does not work in an asynchronous scenario.

  • Alexander Bundschuh

    Is custom error handling possible for REST Polling sender channel?

    We are querying an external Cloud API to pull some data. We will not have data all the time and getting 404 response from the cloud system. We would like to capture this error instead of error in the channel. Error in the channel triggers an alert to interfaces team. It will be lot of alerts if we are not able to capture these error in REST Polling channel.



    • Srini Reddy

      Were you able to find a solution for this issue in Rest polling configuration. We are facing the similar issue with an empty response on every pull which is failing in Interface determination due to the empty tags/payload. As a workaround, we have created a receiver determination and ignore the error. This prevents the message creation in monitoring.

      But the communication channel is throwing error every time when polling happens. It would be great if you could share your views on this issue, if you found the solution already.

  • Hi.

    My scenario is Proxy=>REST sync. I need to send a store id to get some data. It goes well if the store id I send exists. The problem is, when it does not exist, the response contains the message CodeStore not found! without {}. Then the message fails because of exclamation mark. That is what I understand from the error message "Input is not valid JSON at character 19 of CodeStore not found!".

    Is there anything I can do to solve the problem and return the response to Proxy?

  • Hello Alex

    I m new to SAP I have one issue

    For one request I have two different structure response

    How to handle this ?

    Kindly help


    user : "abcd@gmail"
    password: "xtz"

    ######response success####
    succes : "abcd@gmail"
    token: "xtz"

    #####response error#######
    error : "code not found"
    discription: " error with logon"



    • Hi Sahana,

      you can define a custom error rule based on text content "error" or "code not found", eventually using wildcards, like described in one of the examples in the blog, and then define whatever action is suitable for you. In case of a successful response, the error rule won't apply and hence your successful response will be returned, otherwise whatever you defined as action.