The SOAP fault

The SOAP <Fault> element carries error and status information in the SOAP message.

If an error occurs in a web service, a fault message is returned to the client. The basic structure of the fault message is defined in the SOAP specifications. Each fault message can include XML that describes the specific error condition. For example, if an application abend occurs in a CICS web service, a fault message is returned to the client reporting the abend.

CICS can send different types of fault message:

Standard SOAP fault messages are defined by the SOAP specifications or one of the web service specifications that are supported in CICS. The faults report common error conditions, such as malformed SOAP envelopes.
Application SOAP fault messages are generated using the EXEC CICS SOAPFAULT API commands in response to conditions that are detected or handled by the application. The structure of these fault messages is known to the application, but not to CICS.
SOAP handler fault messages are generated by the SOAP handler programs in response to general error handling in CICS. For example, the SOAP handler programs send SOAP faults for abends, XML parsing failures, and other common errors.
Application handler fault messages are generated by CICS SOAP application handlers in response to finding errors when processing the body of a SOAP message. These faults occur during the process of transforming the XML into binary application data or when generating the response.

If an error occurs, the SOAP <Fault> element must be a body entry and must not be present more than once in a <Body> element. The XML elements inside the SOAP <Fault> element are different in SOAP 1.1 and SOAP 1.2.

SOAP 1.1

In SOAP 1.1, the SOAP <Fault> element contains the following elements:

<faultcode>: The <faultcode> element is a mandatory element in the <Fault> element. It provides information about the fault in a form that can be processed by software. SOAP defines a small set of SOAP fault codes covering basic SOAP faults, and this set can be extended by applications.
<faultstring>: The <faultstring> element is a mandatory element in the <Fault> element. It provides information about the fault in a form intended for a human reader.
<faultactor>: The <faultactor> element contains the URI of the SOAP node that generated the fault. A SOAP node that is not the ultimate SOAP receiver must include the <faultactor> element when it creates a fault. An ultimate SOAP receiver is not obliged to include this element, but may do so.
<detail>: The <detail> element carries application-specific error information related to the <Body> element. It must be present if the contents of the <Body> element were not successfully processed. It must not be used to carry information about error information belonging to header entries. Detailed error information belonging to header entries must be carried in header entries.

SOAP 1.2

In SOAP 1.2, the SOAP <Fault> element contains the following elements:

<Code>: The <Code> element is a mandatory element in the <Fault> element. It provides information about the fault in a form that can be processed by software. It contains a <Value> element and an optional <Subcode> element.
<Reason>: The <Reason> element is a mandatory element in the <Fault> element. The <Reason> element contains one or more <Text> elements, each of which contains information about the fault in a different native language.
<Node>: The <Node> element contains the URI of the SOAP node that generated the fault. A SOAP node that is not the ultimate SOAP receiver must include the <Node> element when it creates a fault. An ultimate SOAP receiver is not obliged to include this element, but may do so.
<Role>: The <Role> element contains a URI that identifies the role in which the node was operating at the point the fault occurred.
<Detail>: The <Detail> element is an optional element, which contains application-specific error information related to the SOAP fault codes describing the fault. The presence of the <Detail> element has no significance regarding which parts of the faulty SOAP message were processed.

SOAP fault example and schemas

The following example shows a SOAP fault message that is generated by the application handler, DFHPITP, when processing the body of a SOAP message.

<SOAP-ENV:Fault xmlns="">
   <faultcode>SOAP-ENV:Server</faultcode>
   <faultstring>Conversion to SOAP failed</faultstring>
      <detail>
         <CICSFault xmlns="https://www.ibm.com//software/htp/cics/WSFault">
          DFHPI1008 25/01/2010 14:16:50 IYCWZCFU 00340 XML
          generation failed because of incorrect input 
          (CONTAINER_NOT_FOUND container name) for WEBSERVICE 
          servicename. 
          </CICSFault> 
      </detail> 
</SOAP-ENV:Fault>

Most of the content in this example is common to all fault messages. The <Detail> element contains the unique information that describes the problem that was encountered by the application handler. This specific fault message contains a copy of an error message that is written to the CICS message logs. If you want to parse application handler SOAP faults programmatically, use the following XML schema:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="https://www.ibm.com//software/htp/cics/WSFault"
xmlns:tns="https://www.ibm.com//software/htp/cics/WSFault"
elementFormDefault="qualified">
   <element name="CICSFault" type="string">
      <annotation>
         <documentation>
            The value of this element is a text string that describes a 
            problem encountered during the processing of the Body of a 
            SOAP message. 
         </documentation> 
      </annotation> 
   </element>
</schema>

The general purpose fault messages are more complicated because the <Detail> section can be structured in several different ways. If you want to parse SOAP handler faults programmatically, use the XML schema that is supplied in usshome/schemas/soapfault/soapfault.xsd, where usshome is the value of the USSHOME system initialization parameter.