Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 36 ยท XML and SOAP Messages

SOAP Faults and Error Handling

Learn how SOAP reports errors with Fault elements in 1.1 and 1.2, which fault codes exist, how to design detail elements, and how a client turns faults into exceptions.

Things go wrong in distributed systems: a client sends a malformed message, a database is down, an account is not found. SOAP has one standard way to report such problems: the Fault. A Fault is a special Body content that says "I could not do what you asked", and it replaces the normal response. A good client turns it into an exception; a good service fills it with enough detail to fix the problem without leaking secrets.

Fault in SOAP 1.1

XML
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring>Account 99 does not exist</faultstring>
      <faultactor>http://bank.example/ws/accounts</faultactor>
      <detail>
        <e:AccountNotFound xmlns:e="urn:example:errors"><e:id>99</e:id></e:AccountNotFound>
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>
  • faultcode: a qualified name. The four standard values: VersionMismatch, MustUnderstand, Client (the sender's message is wrong), Server (the receiver failed).
  • faultstring: a human-readable summary.
  • faultactor: the URI of the node that caused the fault (optional).
  • detail: application-specific information, any XML (optional). In 1.1 detail must be present when the fault relates to the Body.

The child elements faultcode, faultstring and so on are unqualified (no namespace) in SOAP 1.1. That oddity trips many hand-written parsers.

Fault in SOAP 1.2

XML
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <env:Fault>
      <env:Code>
        <env:Value>env:Sender</env:Value>
        <env:Subcode><env:Value>e:AccountNotFound</env:Value></env:Subcode>
      </env:Code>
      <env:Reason><env:Text xml:lang="en">Account 99 does not exist</env:Text></env:Reason>
      <env:Detail>...</env:Detail>
    </env:Fault>
  </env:Body>
</env:Envelope>

SOAP 1.2 improves several things: nested Subcodes for precise categories, a Reason that may be given in several languages (xml:lang), and the elements are properly namespaced. The standard codes are VersionMismatch, MustUnderstand, DataEncodingUnknown, Sender and Receiver.

1.1 1.2 Meaning
Client Sender The message is wrong; retrying the same message will fail again.
Server Receiver The service failed; a retry later may succeed.
VersionMismatch VersionMismatch Unknown envelope namespace.
MustUnderstand MustUnderstand A mandatory header block was not understood.

The Sender/Receiver split tells a client whether to retry. A good client retries Receiver faults (with backoff) and never retries Sender faults.

Producing faults

The following server has a GetAccount operation that can fail in three ways. It builds 1.1 faults with a custom detail element and picks Client or Server correctly.

Node.js A service that returns faults

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Consuming faults

On the client, detecting a fault means looking at the body, not just the status. Here is a small SOAP client wrapper that turns faults into a SoapFault error class carrying the code, text and detail, and decides if a retry makes sense.

Node.js Turning faults into exceptions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Designing good faults

  • Choose the right side. Bad input is a Client/Sender fault. A crashed database is a Server/Receiver fault. This drives retry behavior.
  • Use detail for machine-readable errors. Define error elements in your WSDL (see WSDL structure) so clients can generate typed exceptions, for example AccountNotFoundFault.
  • Write the text for people. Short, clear, no stack traces. Stack traces and SQL fragments in a faultstring are a security leak.
  • Do not hide behind Server. Returning Server for every validation error makes clients retry pointless requests.
  • Keep the transport honest. SOAP 1.1 faults come with HTTP 500, SOAP 1.2 Sender faults may use 400. Never wrap a fault in HTTP 200.
  • Log a correlation id in the fault and your logs so support can find the failing call.

Never return internal exception messages, file paths, SQL or stack traces in a fault. Attackers read them. Log the details on the server and return a generic text plus an error id.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A client sends an order with an unknown product code. Which fault code fits best in SOAP 1.1?

    The message itself is wrong, so it is a Client (SOAP 1.2: Sender) fault. Retrying the same message will not help.
  2. 2. Which is true of the Fault child elements in SOAP 1.1?

    In 1.1 the children of Fault have no namespace. In 1.2 Code, Reason and Detail are qualified.
  3. 3. What does SOAP 1.2 add that 1.1 lacked in faults?

    SOAP 1.2 allows nested Subcodes and several Text elements with xml:lang.
  4. 4. When should a client retry automatically?

    Receiver faults may be temporary. Sender faults will repeat until the message is fixed.

Summary

  • A Fault replaces the normal Body content when a service cannot fulfil a request.
  • SOAP 1.1 uses faultcode, faultstring, faultactor and detail; 1.2 uses Code (with Subcode), Reason, Node, Role and Detail.
  • Client/Sender means fix the message; Server/Receiver means try again later.
  • Put typed, machine-readable errors in detail and describe them in the WSDL.
  • Never leak internals in fault text.

Next: SOAP Styles and Encoding