SOAP Fault
Jakob Jenkov |
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>
| Tweet | |
Jakob Jenkov | |
