Definition

SOAP fault

Robert Sheldon
By

What is a SOAP fault?

A SOAP fault is an error in a Simple Object Access Protocol communication resulting from an incorrect message format, header-processing problems, incompatibility between applications or other issues.

SOAP facilitates communications between computers distributed across a network, even if they run on different operating platforms. SOAP is a highly structured, clearly defined architecture that can support an application programming interface.

Multiple standard protocols can carry SOAP messages, including the Hypertext Transfer Protocol, or HTTP; Simple Mail Transfer Protocol, or SMTP; and Transmission Control Protocol, or TCP.

A SOAP message is a specific type of Extensible Markup Language (XML) document that includes an <Envelope> element at the top level. The <Envelope> element must contain a <Body> element and can also contain an optional <Header> element.

The components of a SOAP message: envelope, header and body.
SOAP messages are XML documents that are composed of three basic building blocks. The fault message is an optional fourth building block.

When a SOAP fault occurs, a special type of SOAP message is generated that includes information about where the error originated and what caused it. The information is embedded in a <Fault> element, which itself is embedded in the document's <Body> element. The <Body> element can contain only one <Fault> element and cannot contain any other elements.

A SOAP message that contains a <Fault> element is known as a fault message. Here is an XML code snippet showing the basic structure of a SOAP fault message.

<env:Envelope xmlns:env=http://www.w3.org/2003/05/soap-envelope>
 <env:Body>
 <env:Fault>
 <Fault subelements>
 </env:Fault>
 </env:Body>
</env:Envelope>

The URL in the opening <Envelope> tag points to the XML namespace for the more recent SOAP 1.2 specification, as opposed to SOAP 1.1. The structure is the same for both editions, which are actively used.

In this case, the <Fault> element includes the <Fault subelements> element. This is a placeholder for the various subelements, which provide the data about the specific fault. The subelements supported by the <Fault> element depend on whether you're working with SOAP 1.1 or SOAP 1.2.

SOAP 1.1 supports these subelements in the <Fault> element:

  • <faultcode> -- a mandatory element for identifying the type of fault. The SOAP standard defines a small set of type codes that can be specified in this element; however, they can be extended for specific applications.
  • <faultstring> -- a mandatory element for providing human-readable information about the nature of the fault.
  • <faultactor> -- an optional element for specifying the Uniform Resource Identifier (URI) of the SOAP node that was the source of the fault.
  • <detail> -- an optional element for providing application-specific error information. This element is required if the contents of the <Body> element cannot be otherwise processed.

The subelements changed in SOAP 1.2, although most share a similar purpose. SOAP 1.2 supports these subelements in the <Fault> element:

  • <Code> -- a mandatory element for identifying the type of fault. This element is similar to <faultcode> in SOAP 1.1, except it provides more extensive identification.
  • <Reason> -- a mandatory element for specifying human-readable information about the nature of the fault. This element is similar to <faultstring> in SOAP 1.1.
  • <Node> -- an optional element for providing the URI of the SOAP node that was the source of the fault. This element is similar to <faultactor> in SOAP 1.1.
  • <Role> -- an optional element for specifying the operational role of the SOAP node at the time of the fault.
  • <Detail> -- an optional element for providing application-specific error information. This element is similar to <detail> in SOAP 1.1.

Any node that participates in the SOAP communication can generate a fault message. If a node sends a SOAP request and an error is encountered, the receiving node transmits a fault message to the original node with information about the error. For example, a client might submit a request to a web server that relies on a particular service to carry out its functions. If the service is down, the server might return a SOAP fault message to the client with details about the error.

This was last updated in April 2023

Continue Reading About SOAP fault