Tech and Media Labs
This site uses cookies to improve the user experience.




SOAP Fault

Jakob Jenkov
Last update: 2014-05-23

The SOAP Fault element is returned inside the Body element from a web service (or intermediary node) in case an error occurs while processing the received SOAP message.

Here is a sample SOAP Fault element (Fault element marked in bold):

<?xml version="1.0"?>
<env:Envelope  xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
    <env:Body>
        <env:Fault>

          <env:Code>
            <env:Value>env:Sender</env:Value>
          </env:Code>

          <env:Reason>
            <env:Text xml:lang="en-US">Processing error</env:Text>
            <env:Text xml:lang="da">Processerings-fejl</env:Text>
          </env:Reason>

        </env:Fault>
    </env:Body>
</env:Envelope>

SOAP Fault Structure

A SOAP Fault element has the following structure:

<env:Fault>

  <env:Code>
    <env:Value>env:Sender</env:Value>
    <env:Subcode>
        <env:Value>env:Sender</env:Value>
        <env:Subcode> <-- recursive Subcode's possible -->
        </env:Subcode>
    </env:Subcode>
  </env:Code>

  <env:Reason>
   <env:Text xml:lang="en-US">Error in Input Data</env:Text>
   <env:Text xml:lang="da">Fejl i input data</env:Text>
  </env:Reason>

  <env:Node>http://jenkov.com/theNodeThatFailed</env:Node>

  <env:Role>
    http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver
  </env:Role>

  <env:Detail
    <jj:maxRelayTime
        xmlns:jj="http://jenkov.com" >10000</jj:MaxRelayTime>
  </env:Detail>

</env:Fault>

The Code and Reason elements are mandatory. The Node, Role and Detail elements are optional.

Code

The Code element is mandatory. Inside the Code element you can nest a Value element, and optionally a Subcode element if you need to break down the error code into subcodes.

The Value child element can only contain one of value listed below. The values have to be "name space expanded". This means that if you have mapped the SOAP Envelope name space in the SOAP message to the prefix "env:", you need to prefix the values in the list below with "env:" too. For instance, "env:Sender".


Value Description
VersionMismatch The node that reported this error found a root element in the SOAP message that was not a valid Envelope element
 
MustUnderstand The node returning this fault did not understand a certain header child element - a header child element containing the "mustUnderstand" attribute, and targeted at the node returning the error. In other words, the node returning the fault did not understand the header element it was supposed to understand.
 
DataEncodingUnknown The node returning the fault did not understand the header element encoding (encodingStyle attribute) it was supposed to understand (the header was targeted at the node).
 
Sender The message was incorrectly formed or does not contain valid data, or lacks data etc. In other words, the sender sent a bad SOAP message.
 
Receiver The receicer of the SOAP message failed to process the message. The blame is the receivers, and the receivers alone. For instance, if the web service needs a database and the database is down.

You can read more about the SOAP Fault codes in the SOAP spec - fault codes section.

The Subcode elements can contain whatever values inside their child Value element you decide yourself. Subcode elements can contain other Subcode elements inside them, nested recursively.

Here is an example Code element:

<env:Code>

  <env:Value>env:Sender</env:Value>

  <env:Subcode>
    <env:Value>env:Sender</env:Value>
    <env:Subcode> <-- recursive Subcode's possible -->
    </env:Subcode>
  </env:Subcode>

</env:Code>

Reason

The Reason element is mandatory. The Reason element can contain one or more Text elements as children. These Text elements should contain the cause (reason) of the fault, in whatever languages necessary. The lang attribute of Text element should contain the ISO language code for the given text.

Here is an example that contains the same error message in both english and danish:

<env:Reason xmlns:xml="http://www.w3.org/XML/1998/namespace" >
 <env:Text >Error in Input Data</env:Text>
 <env:Text xml:lang="da">Fejl i input data</env:Text>
</env:Reason>

Node

The Node element is optional. The Node element should contain a URI identifying the node in which the Fault occurred. How this URI identifies the node is up to you.

Here is an example:

<env:Node>http://jenkov.com/theNodeThatFailed</env:Node>

Role

The Role element is optional. The Role element should contain the role of the node in which the fault occurred. The Role element is optional. These roles are explained in the SOAP roles text. Here is an example:

<env:Role>
    http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver
</env:Role>

Detail

The Detail element is optional. The Detail element should contain child elements which contain more detail about the fault that occurred. You cannot put text directly into the Detail element. All text should be nested inside child elements of the Detail element.

All child elements of the Detail element should be name space qualified, meaning they should belong to your own, custom name space.

Here is an example:

  <env:Detail
    <jj:maxRelayTime
        xmlns:jj="http://jenkov.com" >10000</jj:MaxRelayTime>
  </env:Detail>

Jakob Jenkov




Copyright  Jenkov Aps
Close TOC