SOAP Fault Message Structure

SOAP Web Service Tutorials - Herong's Tutorial Examples

∟SOAP Fault Message Structure

This section provides a description of the SOAP fault message structure and a sample message.

A SOAP fault message is a special SOAP message used to carry error information. It must have only one body child element called "Fault" element with the following structure:

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Header>
  ...
 </env:Header>
 <env:Body>
  <env:Fault>
   <env:Code> (required)
    <env:Value>env:VersionMismatch | env:MustUnderstand | Sender
       | DataEncodingUnknown | Receiver</env:Value> (required)
    <env:Subcode> (optional)
     <env:Value>text</env:Value> (required)
      <env:Subcode> (optional)
       ...
      </env:Subcode>
    </env:Subcode>
   </env:Code>
   <env:Reason> (required)
    <env:Text xml:lang="languageCode">text<env:Text> (required)
    <env:Text xml:lang="languageCode">text<env:Text> (optional)
    ...
   </env:Reason>
   <env:Node> (optional)
    http://herong.com/processingNode
   </env:Node>
   <env:Role> (optional)
    http://herong.com/processingRole
   </env:Role>
   <env:Detail ...> (optional)
    ... (any XML structure)
   </env:Detail>
  </env:Fault>
 </env:Body>
</env:Envelope>

Note that:

"Fault" must be the only child element of "Body".
"Code" and "Reason" are required child elements. "Node", "Role" and "Detail" are optional child elements.
"Code", "Reason", "Node", "Role" and "Detail" must appear in the predefined order.
"Code.Value" is a required element. It must contain one of the 5 predefined values.
"Subcode.Value" is also a required element. But it may contain any text information.
"Code.Subcode" is an optional element.
"Subcode.Subcode" is a recursive structure.
The first "Reason.Text" element is required. Additional "Reason.Text elements are optional.
"Reason.Text[@xml:lang]" is a required attribute, which specifies an XML standard language code.
"Node" specifies which SOAP node generated this fault message.
"Role" specifies what role this node was playing when this fault occurred.
"Detail" is free format XML structure to supplier any detailed fault information.

To give an idea of how a SOAP fault message looks like, I have copied the example #6a from the SOAP 1.2 specification here:

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
            xmlns:rpc='http://www.w3.org/2003/05/soap-rpc'>
  <env:Body>
   <env:Fault>
     <env:Code>
       <env:Value>env:Sender</env:Value>
       <env:Subcode>
        <env:Value>rpc:BadArguments</env:Value>
       </env:Subcode>
     </env:Code>
     <env:Reason>
      <env:Text xml:lang="en-US">Processing error</env:Text>
      <env:Text xml:lang="fr-CA">Error</env:Text>
     </env:Reason>
     <env:Detail>
      <e:myFaultDetails 
        xmlns:e="http://travelcompany.example.org/faults">
        <e:message>Name does not match card number</e:message>
        <e:errorcode>999</e:errorcode>
      </e:myFaultDetails>
     </env:Detail>
   </env:Fault>
 </env:Body>
</env:Envelope>