SOAP 1.1 Fault

I’ve spent some time recently working with SOAP 1.1 <faultcode> and wanted to compress some of that research into one place where I could find it again in future. There is no original insights in this post, it’s really just to avoid me having to search the internet for it in future.

 faultcode (mandatory)

The SOAP 1.1 specification (W3C, 2000) specifies 4 standard values for the <faultcode> which are detailed below. In addition faultcodes can be defined as required by the systems utilising the protocol. The guidance is to use two elements seperated by a dot, with the left element a category in which the right elements being specific examples.

For example, here is an example of a SOAP 1.1 fault used by Microsoft XMLA.

<?xml version="1.0"?>  
   <SOAP-ENV:Envelope  
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"  
   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">  
      <SOAP-ENV:Fault>  
         <faultcode>XMLAnalysisError.0x80000005</faultcode>  
         <faultstring>The XML for Analysis provider encountered an error.</faultstring>  
         <faultactor>XML for Analysis Provider</faultactor>  
         <detail>  
<Error  
ErrorCode="2147483653"  
Description="An unexpected error has occurred."  
Source="XML for Analysis Provider"  
HelpFile="" />  
         </detail>  
      </SOAP-ENV:Fault>  
</SOAP-ENV:Envelope>

(Microsoft, 2022)

As you can see the <faultcode> is defined as XMLAnalysisError.0x80000005. The category being XMLAnalysisError and the specific kind of error 0x80000005.

<faultcode>SOAP-ENV:VersionMismatch</faultcode>

Invalid namespace detected in the SOAP Envelope, the only valid value for the namespace is:

http://schemas.xmlsoap.org/soap/envelope/
<faultcode>SOAP-ENV:MustUnderstand</faultcode>

The SOAP Header may contain elements marked as mustUnderstand, this fault code should be used if the processing party does not understand that element.

<faultcode>SOAP-ENV:Client</faultcode>

Indicates that the message is badly formed or lacked the right information to be able to be processed.

<faultcode>SOAP-ENV:Server</faultcode>

Used when errors are generated during the processing of a well-formed message.

 faultstring (mandatory)

A human readable explanation of the fault.

 faultactor

Indicates the actor which caused the fault and is used to name the system where the processing issue eminated. The message may be handed off to several other services for eventual processing and should a fault occur that service needs to be named as the fault actor.

 detail

Provides application specific error information within their own namespace.

Example messages

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <SOAP-ENV:Fault>
            <faultcode>SOAP-ENV:Client</faultcode>
            <faultstring>Message does not have necessary info</faultstring>
            <faultactor>http://gizmos.com/order</faultactor>
            <detail>
                <PO:order xmlns:PO="http://gizmos.com/orders/">
                    Quantity element does not have a value
                </PO:order>
                <PO:confirmation xmlns:PO="http://gizmos.com/confirm">
                    Incomplete address: no zip code
                </PO:confirmation>
            </detail>
        </SOAP-ENV:Fault>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
       <SOAP-ENV:Fault>
           <faultcode>SOAP-ENV:MustUnderstand</faultcode>
           <faultstring>SOAP Must Understand Error</faultstring>
       </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
       <SOAP-ENV:Fault>
           <faultcode>SOAP-ENV:Server</faultcode>
           <faultstring>Server Error</faultstring>
           <detail>
               <e:myfaultdetails xmlns:e="Some-URI">
                 <message>
                   My application didn't work
                 </message>
                 <errorcode>
                   1001
                 </errorcode>
               </e:myfaultdetails>
           </detail>
       </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
  • Fault must be present in the Body and must be the only element within it. There can only be one fault in the body.

References

ReferenceTitle
W3C (2000)Simple Object Access Protocol (SOAP) 1.1 Specification - https://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383500
Microsoft (2022)Microsoft XML for Analysis (XMLA) SOAP Fault - https://learn.microsoft.com/en-us/analysis-services/multidimensional-models-scripting-language-assl-xmla/handling-errors-and-warnings-xmla?view=asallproducts-allversions#handling_soap_faults