|
|
SOAP Fault
The Fault element indicates that an error occurred while processing a
SOAP request. This element is used to carry error and/or status information
within a SOAP message and only appears in response messages. The SOAP
Fault element must appear as a body entry under the Body
element and must not appear more than once within a Body
element.
Sub elements of the SOAP Fault element
A faultcode element followed by a faultstring element followed by an
optional faultactor element and an optional detail element. Each of these
children is described in the following:
|
Name
|
Syntax
|
Description
|
|
faultcode
|
<faultcode xmlns=''>
QName</faultcode>
|
The faultcode element is of type QName and indicates what fault
occurred. Several existing categories of fault code are defined, all in
the
http://schemas.xmlsoap.org/soap/envelope/
namespace.
VersionMismatch indicates that the recipient of a message did not
recognize the namespace name of the Envelope element. MustUnderstand
indicates that the recipient of an element child of the Header element
had a soap:mustUnderstand attribute but that element was not understood
by the recipient. Client indicates the SOAP message did not contain all
the required information in order for the recipient to process it. This
could mean that something was missing from inside the Body element.
Equally, an expected extension inside the Header element could have been
missing. In either case, the sender should not resend the message
without correcting the problem. Server indicates that the recipient of
the message was unable to process the message because of some
server-side problem. The message contents were not at fault; rather,
some resource was unavailable or some processing logic failed for a
reason other than an error in the message. The sender may legitimately
resend the message at a later time. All these fault codes may be
followed by a period and a further string providing more detailed
information about the error; for example,
Client.InvalidParameter.
|
|
faultstring
|
<faultstring xmlns=''>
string </faultstring>
|
The faultstring element is of type string and provides a human-readable
description of whatever fault occurred.
|
|
faultactor
|
<faultactor xmlns=''>
uriReference </faultactor>
|
The faultactor element is of type uriReference and indicates the source
of the fault. This may be the ultimate recipient of the request message,
in which case the element is optional. Alternatively, the source of the
fault may be an intermediary somewhere in the path the message took to
get from the sender to the ultimate recipient. In this case the element
must be present.
|
|
detail
|
<detail xmlns=''> any number of elements in any namespace
</detail>
|
The detail element is used to carry application-specific error
information and may be annotated with any number of attributes from any
namespace, and may have any number of namespace-qualified element
children. The detail element must be present if the fault is the result
of the recipient being unable to process the Body element. The detail
element is not used to provide error information in the case of the
recipient being unable to process an element child of the Header
element. In such cases, error information is placed inside the Header
element.
The detail element is intended for carrying application specific error
information related to the Body element. It MUST be present if the
contents of the Body element could not be successfully processed. It
MUST NOT be used to carry information about error information belonging
to header entries. Detailed error information belonging to header
entries MUST be carried within header entries. The absence of the detail
element in the Fault element indicates that the fault is not related to
processing of the Body element. This can be used to distinguish whether
the Body element was processed or not in case of a fault situation.
All immediate child elements of the detail element are called detail
entries and each detail entry is encoded as an independent element
within the detail element. The encoding rules for detail entries are as
follows:
· A detail entry
is identified by its fully qualified element name, which consists of the
namespace URI and the local name. Immediate child elements of the detail
element MAY be namespace-qualified.
· The SOAP
encodingStyle attribute MAY be used to indicate the encoding style used
for the detail entries
|
SOAP Fault Codes
The default SOAP faultcode values are defined in an extensible manner that
allows for new SOAP faultcode values to be defined while maintaining
backwards compatibility with existing faultcode values. The mechanism used is
very similar to the 1xx, 2xx, 3xx etc basic status classes classes defined in
HTTP. However, instead of integers, they are defined as XML qualified names.
The character "." (dot) is used as a separator of faultcode values indicating
that what is to the left of the dot is a more generic fault code value than
the value to the right.
The set of faultcode values defined in SOAP 1.1 is:
|
Name
|
Meaning
|
|
VersionMismatch
|
The processing party found an invalid namespace for the SOAP Envelope
element.
|
|
MustUnderstand
|
An immediate child element of the SOAP Header element that was either
not understood or not obeyed by the processing party contained a SOAP
mustUnderstand attribute with a value of "1".
|
|
Client
|
The Client class of errors indicate that the message was incorrectly
formed or did not contain the appropriate information in order to
succeed. For example, the message could lack the proper authentication
or payment information. It is generally an indication that the message
should not be resent without change.
|
|
Server
|
The Server class of errors indicate that the message could not be
processed for reasons not directly attributable to the contents of the
message itself but rather to the processing of the message. For example,
processing could include communicating with an upstream processor, which
didn't respond. The message may succeed at a later point in time.
|
SOAP 1.1 allows custom fault codes to appear inside the faultcode element,
through the use of the "dot" notation. Use of this mechanism to extend the
meaning of the SOAP 1.1-defined fault codes can lead to namespace collision.
Therefore, its use should be avoided, as doing so may cause interoperability
issues when the same names are used in the right-hand side of the "." (dot) to
convey different meaning.
Instead, the WS-I Basic Profile 1.0 encourages the use of the fault codes
defined in SOAP 1.1, along with additional information in the detail element
to convey the nature of the Fault.
Alternatively, it is acceptable to define custom fault codes in a namespace
controlled by the specifying authority.
A number of specifications have already defined custom fault codes using
the "." (dot) notation. Despite this, their use in future specifications is
discouraged.
|
R1004
|
When a MESSAGE contains a faultcode element the content of that element
SHOULD be one of the fault codes defined in SOAP 1.1 or a namespace
qualified fault code.
|
|
R1031
|
When a MESSAGE contains a faultcode element the content of that element
SHOULD NOT use of the SOAP 1.1 "dot" notation to refine the meaning of the
Fault.
|
It is recommended that applications that require custom fault codes either
use the SOAP 1.1 defined fault codes and supply additional information in the
detail element, or that they define these codes in a namespace that is
controlled by the specifying authority.
For example,
INCORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
xmlns:c='http://example.org/faultcodes' >
<faultcode>soap:Server.ProcessingError</faultcode>
<faultstring>An error occurred while processing the message
</faultstring>
</soap:Fault>
CORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
xmlns:c='http://example.org/faultcodes' >
<faultcode>c:ProcessingError</faultcode>
<faultstring>An error occured while processing the message
</faultstring>
</soap:Fault>
CORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >
<faultcode>soap:Server</faultcode>
<faultstring>An error occured while processing the message
</faultstring>
</soap:Fault>
A SOAP Fault is a SOAP message that has a single child element of
the soap:Body element, that element being a soap:Fault element. The
Profile restricts the content of the soap:Fault element to those
elements explicitly described in SOAP 1.1.
[WS-I
Basic Profile 1.0]
|
R1000
|
When a MESSAGE contains a soap:Fault element, that element MUST NOT have
element children other than faultcode, faultstring, faultactor and detail.
|
INCORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
<faultcode>soap:Client</faultcode>
<faultstring>Invalid message format</faultstring>
<faultactor>http://example.org/someactor</faultactor>
<detail>There were <b>lots</b> of elements in the
message
that I did not
understand
</detail>
<m:Exception xmlns:m='http://example.org/faults/exceptions'>
<m:ExceptionType>Severe</m:ExceptionType>
</m:Exception>
</soap:Fault>
CORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
<faultcode>soap:Client</faultcode>
<faultstring>Invalid message format</faultstring>
<faultactor>http://example.org/someactor</faultactor>
<detail>
<m:msg
xmlns:m='http://example.org/faults/exceptions'>
There were
<b>lots</b> of elements in the message that I did not understand
</m:msg>
<m:Exception
xmlns:m='http://example.org/faults/exceptions'>
<m:ExceptionType>Severe</m:ExceptionType>
</m:Exception>
</detail>
</soap:Fault>
The children of the soap:Fault element are local to that element,
therefore namespace qualification is
unnecessary.[WS-I
Basic Profile 1.0]
|
R1001
|
When a MESSAGE contains a soap:Fault element its element children
MUST be unqualified.
|
For example,
INCORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
<soap:faultcode>soap:Client</soap:faultcode>
<soap:faultstring>Invalid message format</soap:faultstring>
<soap:faultactor>http://example.org/someactor</soap:faultactor>
<soap:detail>
<m:msg
xmlns:m='http://example.org/faults/exceptions'>
There were
<b>lots</b> of elements in the message that
I did not understand
</m:msg>
</soap:detail>
</soap:Fault>
CORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
xmlns=''>
<faultcode>soap:Client</faultcode>
<faultstring>Invalid message format</faultstring>
<faultactor>http://example.org/someactor</faultactor>
<detail>
<m:msg
xmlns:m='http://example.org/faults/exceptions'>
There were
<b>lots</b> of elements in the message that
I did not
understand
</m:msg>
</detail>
</soap:Fault>
SOAP Fault Processing
When a Fault is generated, no further processing should be performed. In
request-response exchanges, a Fault message will be transmitted to the sender
of the request message, and some application level error will be flagged to
the user.
[WS-I
Basic Profile 1.0]
|
R1028
|
When a Fault is generated by a RECEIVER,
further processing SHOULD NOT be performed on the SOAP message
aside from that which is necessary to rollback, or compensate for, any
effects of processing the message prior to the generation of the
Fault.
|
|
R1029
|
Where the normal outcome of processing a SOAP message would have resulted
in the transmission of a SOAP response, but rather a SOAP Fault is
generated instead, a RECEIVER MUST transmit a SOAP Fault
message in place of the response.
|
|
R1030
|
A RECEIVER that generates a SOAP Fault SHOULD notify
the end user that a SOAP Fault has been generated when practical,
by whatever means is deemed appropriate to the circumstance.
|
|
|
