SOAP Fault Element Structure in XML Error Handling

This article provides an overview of the SOAP Fault element used for error handling in SOAP-based web services. When an error occurs during processing, the server returns a SOAP Fault element within the message Body instead of the standard response payload. The structure of this element differs slightly between the SOAP 1.1 and SOAP 1.2 specifications, but both define standardized sub-elements to convey error codes, descriptions, and application-specific diagnostics.

The Role of the Fault Element

In a SOAP envelope, the <Fault> element resides directly inside the <Body> element. It indicates that an error occurred while processing the request. A SOAP response containing a fault typically uses the HTTP 500 (Internal Server Error) status code.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <!-- Sub-elements go here -->
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

SOAP 1.1 Fault Structure

Under the SOAP 1.1 specification, the <Fault> element contains four primary sub-elements:

  1. <faultcode> (Required): An algorithm-friendly code identifying the category of the fault. Standard SOAP 1.1 fault codes include:
    • VersionMismatch: The processing node found an invalid namespace for the SOAP Envelope element.
    • MustUnderstand: An immediate child element of the SOAP Header with mustUnderstand="1" was not understood.
    • Client: The message was incorrectly formed or lacked necessary information.
    • Server: The message was valid, but an error occurred on the server while processing.
  2. <faultstring> (Required): A human-readable explanation of the error.
  3. <faultactor> (Optional): The URI of the source that caused the fault along the message path.
  4. <detail> (Optional): Application-specific error data. If the error is related to the <Body> element, this element is mandatory; if related to a <Header>, it must not be present.

SOAP 1.1 Example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring>Invalid Account Number</faultstring>
      <faultactor>http://example.com/accountservice</faultactor>
      <detail>
        <errorDetails xmlns="http://example.com/errors">
          <errorCode>4001</errorCode>
          <message>The provided account number does not exist.</message>
        </errorDetails>
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

SOAP 1.2 Fault Structure

The SOAP 1.2 specification updated the naming and hierarchy of the sub-elements within <soap:Fault> to improve consistency and internationalization:

  1. <soap12:Code> (Required): Contains a mandatory <soap12:Value> (e.g., soap12:Sender, soap12:Receiver, soap12:VersionMismatch, soap12:MustUnderstand, soap12:DataEncodingUnknown) and an optional nested <soap12:Subcode> for finer granularity.
  2. <soap12:Reason> (Required): Contains one or more <soap12:Text> elements providing a human-readable explanation, each specifying an xml:lang attribute.
  3. <soap12:Node> (Optional): Identifies the specific SOAP node that generated the fault via a URI.
  4. <soap12:Role> (Optional): Identifies the role the node was operating in when the fault occurred.
  5. <soap12:Detail> (Optional): Carries application-specific error details.

SOAP 1.2 Example

<soap12:Envelope xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <soap12:Fault>
      <soap12:Code>
        <soap12:Value>soap12:Sender</soap12:Value>
        <soap12:Subcode>
          <soap12:Value xmlns:m="http://example.com/errors">m:InvalidAccount</soap12:Value>
        </soap12:Subcode>
      </soap12:Code>
      <soap12:Reason>
        <soap12:Text xml:lang="en-US">The provided account number does not exist.</soap12:Text>
      </soap12:Reason>
      <soap12:Node>http://example.com/nodes/auth</soap12:Node>
      <soap12:Role>http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver</soap12:Role>
      <soap12:Detail>
        <errorDetails xmlns="http://example.com/errors">
          <errorCode>4001</errorCode>
        </errorDetails>
      </soap12:Detail>
    </soap12:Fault>
  </soap12:Body>
</soap12:Envelope>