SOAP Fault Message Structure

<< SOAP Message Structure

<< Herong's Tutorial Notes on Web Service and SOAP

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> (opitonal)
    ...
   </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>

Last update: 2007.

Sections in This Chapter

SOAP Generic Message Structure

SOAP Fault Message Structure