Skip to Content
Author's profile photo Former Member

Handling Web Service SOAP Fault Responses in SAP NetWeaver XI

h3. Introduction When consuming a web service, it’s nice when all is working smoothly – the web service receives valid input from the web service client and, in turn, returns a valid response to that client. It would be nice if all services always “worked” in this way or just “worked” period. Well… back to reality. Sometimes bad data is inevitably supplied or changes take place in the implementation of the web service and a SOAP fault response containing application specific error information is sent back to the client. When SAP NetWeaver XI is in the middle, and the receiver SOAP adapter is used to call a web service, technically, XI (specifically the receiver SOAP adapter) is the web service client that initiates the call to a web service and receives its response. XI then passes the response back to the original sender that passed the initial request to XI. In successful cases, this is straightforward. However, in problem cases, the web service will return a SOAP fault message which will either result in a +system error+ message or an +application error+ message in XI, usually with a HTTP 500 response code. In the system error case, there are not many options as far as capturing and handling specifics within the SOAP fault. For application errors, however, the fault payload can be captured/accessed and, if necessary, mapped back to the original sender’s format. For you seasoned XI experts, none of this is news to you. However, there have recently been some threads on SDN on how to handle these SOAP fault responses, so… In this blog, a closer look is taken at handling SOAP fault application error messages when using SAP NetWeaver XI. It also illustrates how a +fault mapping+ can be used to map a SOAP fault back to a corresponding fault format that the original sender can understand. It also discusses some differences to consider in handling SOAP faults when using the standard soap mode vs. the “nosoap” mode.

h3. SOAP Fault – Application Error Message element within the SOAP Fault message as specified for {code:html}SOAP 1.1{code}. An example within the given link is provided: h3. HTTP Return Codes – soap/nosoap modes h3. RFC to SOAP Example The main example in this blog shows a synchronous RFC to SOAP scenario using a custom RFC client application calling a demo XMethods web service called “Currency Exchange Rate” that returns the currency exchange rate between two countries. There are many threads and blogs on SDN on how to set up a basic RFC to SOAP scenario (just do a SDN search), so this is NOT a “step-by-step”. Instead, the focus is on the fault/exception handling aspects of this scenario. h4. About XMethods Currency Exchange Service The “Currency Exchange Service” web service, along with the WSDL (, is provided on the XMethods website at ( It’s an +RPC style+ service and the basic SOAP request and response (successful case), looks like this:

h5. Request h5. Response The above is an example of a valid request/response case. Now, what if I submitted the request with some invalid input – say +InvalidCountry+ and US for “Country1” and “Country2” respectively as shown:

h5. Invalid Request h5. SOAP Fault – Application Error Response h4. RFC “Stub” Shown below is my remote-enabled RFC “stub” (just parameters, no implementation code) that will, more-or-less, serve as the main client/sender in my RFC to SOAP scenario to send the two “Country” input data to the “Currency Exchange Service” web service. Notice the declaration of the “Exceptions” parameter +CURR_EXCHANGE_APP_ERROR+. The fault payload from the web service will map to this RFC exception. image h4. Integration Repository (Design) Below is my imported RFC Z_CURRENCY_EXCHANGE_1. The imported RFC metadata will serve as the sender/outbound/synchronous interface and also contains the relevant request/response/exception message types to be used the corresponding mappings. Displayed is only the RFC Exception message type. image For the inbound interface (corresponding to the web service invocation), the Currency Exchange Service WSDL is imported and used for the input and output message types. Based on the fault response payload received while testing the service, a fault message type XML schema (xsd) was created externally and imported as an External Definition, which is what is displayed as “electric-detail” below. image Also regarding the import of the WSDL for the Currency Exchange Service, a couple of things to note: ** ** However, even with this option, if the WSDL is imported as is, the namespace for the messages +getRate+ and +getRateResponse+ do not get set to the correct/necessary namespace +urn:xmethods-CurrencyExchange+ as shown above. As a work-around, the WSDL can be tweaked externally and re-imported. Basically, the target namespace reflected in the first line for the definitions element should be adjusted to reflect the namespace “urn:xmethods-CurrencyExchange” and not ““. The final import should look like this: image Regarding the Interface Mapping, a fault mapping must be configured. In order to be able to configure a fault mapping, a Fault Message Type should be specified within both the source and target interface. Then when clicking on the “Read Interfaces” button within the Interface Mapping, a “Fault” tab will appear. image Below is a shot of the fault message mapping that maps the Currency Exchange Service fault payload (“electric-detail”) to the RFC exception. image Note that the “Name” field should reflect the RFC exception name. In this case +CURR_EXCHANGE_APP_ERROR+. image h4. Integration Directory (Configuration) As far as configuration is concerned, no special configuration is needed as it relates to fault handling. Standard configuration for the channels (sender RFC/receiver SOAP), receiver determination, etc. should be maintained for this scenario. h4. Runtime – Sample Test Run Using the function module test tool is sufficient in initiating a runtime test scenario for this RFC to SOAP example once the configuration has been complete. Below are some screen shots within the function module test tool and the XI monitoring tool to illustrate what happens at runtime. For comparison, both success and error cases are provided.

h5. Success Case Initiating the request… image Monitoring the request and mapped payloads… image Monitoring successful response and mapped payloads… image Successful response back to original RFC sender… image h5. Error Case Bad data will be passed as one of the parameters… image An application error will result… image A look at the request part and mapped payloads… image A look at the application error response fault payload… As you can see, the fault mapping is invoked where the fault payload is mapped back to the RFC exception. image Ultimately, the RFC sender receives the application error message as an RFC exception. image

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Michal Krawczyk
      Michal Krawczyk
      Hi Jin,

      hope this will cut down the number of all SOAP fault questions on XI forum πŸ™‚

      thank you Jin πŸ™‚


      Author's profile photo Former Member
      Former Member
      Blog Post Author
      Hi Michal -

      Yes, hopefully some soap fault inquiries will be cut down, but I realize there are some gaps regarding faults to be addressed, but this blog was pretty long on its own.


      Author's profile photo Wendy Wu
      Wendy Wu
      Hi Jin,

      Great job.
      But do you have more information on how to handle
      the system error? like HTTP 500 - Internal Server Error.What are the most common causes for such kind of error in SOAP Adatper ->Exteral Web Services?

      Thanks in advance.

      Author's profile photo Bhavesh Kantilal
      Bhavesh Kantilal

      Jin,You have also pointed that handling System Error's in XI is not an easy task,In the system error case, there are not many options as far as capturing and handling specifics within the SOAP fault<br/><br/>Now my questions,<br/><br/>1. If my webservice does not provide the details tag and what If I want to propgate this back to the calling application? Why not a fault message mapping getting triggered here as well? Why does no Details tag in the fault message imply that this is a System Error?<br/><br/>2. Would a BPM solution with exception handler separate for the application error and the System Error allow one to access the Fault Message from the Webservice ( even though it does not contain the Detail tag in the fault message? ).<br/><br/>Thanks once again for this blog,<br/><br/>Regards<br/>Bhavesh

      Author's profile photo Former Member
      Former Member
      Blog Post Author

      Hi Bhavesh - Jin

      Author's profile photo Former Member
      Former Member
      Thanks for Jin for wonderful blog . Infact i am having problem what Bhavesh said in pont 1. I was trying hard to get fault message response t osender with out detail tag element. 

      As I am not getting Details element tag for fault error message it possible for my webservice provider to provide me detial tag element for application errors. what does web service provider has to do to provide me Detail element tag.


      Author's profile photo Former Member
      Former Member

      When i tried with the above mentioned Steps.. in SXMB_MONI is still showing the system Error ..

      I created the Message Type as per the SOAP FAULT  and Exported and Imported as a External Definition...

      Did i miss any thing

      Author's profile photo Former Member
      Former Member
      Blog Post Author

      Hi - Jin

      Author's profile photo Former Member
      Former Member
      This weblog will really help in understanding the usage of Fault responses. Expecting a few more weblogs from you.


      Author's profile photo Henrique Pinto
      Henrique Pinto
      That is really a good subject to address, since fault messages are still a "fuzzy" area for XI developers.

      But if we analyze the mass of real questions about fault messages in SDN, we'll see that most of them refer to handling fault messages in BPM, which hasn't be really addressed directly.

      I do think it'd be a really interesting topic for a next blog. πŸ™‚

      Best regards,


      Author's profile photo Former Member
      Former Member
      Blog Post Author
      Hi Henrique -

      Appreciate your feedback... yes, some gaps remain in the topic of handling soap faults.  This blog attempts to tackle a portion of it.


      Author's profile photo Former Member
      Former Member
      Hi Jin,

      The web service link you have provided in your blog is not working. Can you provide link to some web service, which can return a soap fault message for application error.
      I need it to do few testing for nosoap mode.

      Best Regards,

      Author's profile photo Ernesto Cruz
      Ernesto Cruz

      Hi Jin, I am test your tips about this question. The blog is very well.

      A doubt is in the external message that bind the fault message. Could you explain more in this point? or post a help link.


      Author's profile photo David Ramos Valenciano
      David Ramos Valenciano

      Hi Jin,

      we have follow all your steps for create an scenario synchronous RFC to SOAP. But we have several problems when the target system response fault message.

      This is the error that appers in the sxmb_moni:

      <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 

      <!-- Call Adapter -->   <SAP:Error xmlns:SAP="" xmlns:SOAP="" SOAP:mustUnderstand="1">


             <SAP:Code area="HTTP">ADAPTER.HTTP_EXCEPTION</SAP:Code>

             <SAP:P1 />

             <SAP:P2 />

             <SAP:P3 />

             <SAP:P4 />

             <SAP:AdditionalText>HTTP 500 Internal Server Error</SAP:AdditionalText>

             <SAP:ApplicationFaultMessage namespace="" />

             <SAP:Stack />



      This message raise a system error and don´t process the mapping specific for the fault message.

      We are using XI 3.0.

      Could you help us,please??

      Best Regards,

      David Ramos

      Author's profile photo ambuj mishra
      ambuj mishra

      Error you have pasted above comes under System Error. It can't be captured using Fault message as explained in this blog.Fault messages can be used for only Application errors.