skip to content

How does a SOAP 1.2 Fault differ from a SOAP 1.1 Fault in its child elements and its standard fault codes?

level: middleimportance: must knowfreq 28%

answer

  1. renamed, restructured, localised
  2. faultcode grows a hierarchy
  3. faultstring becomes language-tagged text
  4. faultactor splits in two
  5. Client and Server renamed, one code added

basics

~20 s

SOAP 1.1 Faults carry faultcode, faultstring, optional faultactor and detail, coded VersionMismatch, MustUnderstand, Client or Server. SOAP 1.2 uses Code (Value, nested Subcode), Reason (Text per xml:lang), optional Node, Role and Detail, renames Client/Server to Sender/Receiver and adds DataEncodingUnknown.

solid answer

~40 s

In SOAP 1.1 a `Fault` holds `faultcode` (a mandatory QName), `faultstring` (a mandatory human-readable explanation), `faultactor` (a URI, mandatory when a node other than the ultimate destination raised the fault) and `detail` (application error information about the Body). Its codes are `VersionMismatch`, `MustUnderstand`, `Client` and `Server`, refined with dots such as `Client.Authentication`. SOAP 1.2 restructures all of it: `Code` holds a `Value` restricted to `VersionMismatch`, `MustUnderstand`, `DataEncodingUnknown`, `Sender` or `Receiver`, plus optional nested `Subcode` elements whose QName values the application defines; `Reason` holds one or more `Text` elements, each tagged with `xml:lang`; `faultactor` becomes `Node` (which node failed) plus a new `Role` (the role it was acting in); `Detail` stays optional. Every SOAP 1.2 fault child is in the envelope namespace, and the Fault must be the Body's only child.

code

xml · 20 lines
xml
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
    xmlns:p="http://example.org/payments/faults">
  <env:Body>
    <env:Fault>
      <env:Code>
        <env:Value>env:Sender</env:Value>
        <env:Subcode>
          <env:Value>p:CardExpired</env:Value>
        </env:Subcode>
      </env:Code>
      <env:Reason>
        <env:Text xml:lang="en">Card has expired</env:Text>
        <env:Text xml:lang="de">Karte ist abgelaufen</env:Text>
      </env:Reason>
      <env:Detail>
        <p:ExpiredOn>2026-08-31</p:ExpiredOn>
      </env:Detail>
    </env:Fault>
  </env:Body>
</env:Envelope>

go deeper

for a junior

Recall that a Fault reports an error inside the Body, and name its main parts in at least one version: a machine-readable code and a human-readable explanation.

for a middle

Map each SOAP 1.1 fault child and code to its SOAP 1.2 counterpart, and explain why Subcode replaced dot notation and why Reason text carries xml:lang.

for a senior

Explain what a client may infer from a fault in each version: decisions from Code and Subcode, the failing hop from Node or faultactor, and why the presence of detail meant something only in SOAP 1.1.

for a principal

Judge how an estate running both versions should present faults consistently to consumers, including who governs application subcodes and detail entries across teams.

## What a Fault is for A **SOAP Fault** is SOAP's error contract: instead of a normal result, the Body carries a `Fault` element that tells the sender what went wrong, in a form software can branch on and a person can read. Both versions define it, but SOAP 1.2 rebuilt it, and a client or gateway written for one version will misread the other. ## The SOAP 1.1 Fault The SOAP 1.1 Note defines four sub-elements, written without a namespace prefix in its own examples: - **`faultcode`** (mandatory): a qualified name meant for software, such as `SOAP-ENV:Server`. - **`faultstring`** (mandatory): a human-readable explanation, compared by the Note to HTTP's Reason-Phrase and not intended for algorithmic processing. - **`faultactor`** (optional): a URI saying which node on the message path caused the fault. Nodes that are not the ultimate destination MUST include it. - **`detail`**: application-specific error information **related to the Body**. It MUST be present when the Body could not be processed and MUST NOT carry errors belonging to header entries, which travel in header entries instead. Its absence therefore says the fault is not about Body processing. If present, the Fault MUST be a body entry and MUST NOT appear more than once in a Body. ## The SOAP 1.2 Fault SOAP 1.2 Part 1 gives the `Fault` two to five children, in this order, all in the `http://www.w3.org/2003/05/soap-envelope` namespace: 1. **`Code`** (mandatory): a `Value` and an optional `Subcode`, which itself holds a `Value` and may nest another `Subcode`. 2. **`Reason`** (mandatory): one or more `Text` elements, each with a mandatory `xml:lang` attribute; each Text SHOULD use a different language. 3. **`Node`** (optional): the URI of the node that generated the fault. Nodes other than the ultimate receiver MUST include it. 4. **`Role`** (optional): the role the node was acting in when the fault occurred; it MUST be one of the roles that node assumed. 5. **`Detail`** (optional): application-specific error information. To count as a fault message, the Body MUST contain this single `Fault` as its **only** child; a Body with a Fault plus other elements has no SOAP-defined meaning. ## Element by element | SOAP 1.1 | SOAP 1.2 | What changed | |---|---|---| | `faultcode` | `Code` / `Value` + `Subcode` | flat QName with dot refinement becomes a hierarchy | | `faultstring` | `Reason` / `Text xml:lang` | one string becomes one text per language | | `faultactor` | `Node` + `Role` | who failed, now separated from the role it played | | `detail` | `Detail` | presence no longer signals whether the Body was processed | ## The fault codes | SOAP 1.1 `faultcode` | SOAP 1.2 Code `Value` | Meaning | |---|---|---| | `VersionMismatch` | `env:VersionMismatch` | the Envelope's namespace (in 1.2, its name) was not the expected one | | `MustUnderstand` | `env:MustUnderstand` | a mandatory header block aimed at the node was not understood | | (none) | `env:DataEncodingUnknown` | a header block or Body child is scoped with a data encoding the node does not support | | `Client` | `env:Sender` | the message was malformed or lacked what it needed; do not resend unchanged | | `Server` | `env:Receiver` | processing failed for reasons not in the message; a later resend could succeed | ## From dots to subcodes SOAP 1.1 made fault codes extensible with **dot notation**: what is left of a dot is more generic than what is right of it, so `Client.Authentication` is a kind of `Client` fault. SOAP 1.2 removed the dots. The top-level `Value` is now restricted to the five codes of the `env:faultCodeEnum` type, and anything more specific goes in **`Subcode/Value`**, an `xs:QName` the application or a feature defines, typically in its own namespace. Subcodes can nest; SOAP 1.2 sets no limit, and expects few levels in practice. SOAP 1.2 also states that the codes give the context in which `Detail` is interpreted, so a node MUST understand all the fault codes in a fault to interpret its `Detail`. ## Two smaller changes that bite - In SOAP 1.1, the presence of `detail` tells the client the Body was involved. In SOAP 1.2, the presence of `Detail` has **no significance** as to which parts of the message were processed. - SOAP 1.1 defined the `MustUnderstand` code but gave no structure for saying which header failed. SOAP 1.2 adds the `NotUnderstood` header block for exactly that, placed in the fault message's Header, not in `Detail`. How each fault code maps to an HTTP status is decided by the transport binding, not by the Fault element itself.

  • Why does SOAP 1.2's Reason element hold several Text children?
    So one fault can explain itself in several languages: each `Text` carries a mandatory `xml:lang`, and each SHOULD use a different value. Like SOAP 1.1's `faultstring`, it is meant for people and is not intended for algorithmic processing, so clients decide on `Code` and `Subcode`, never on the wording.
  • Can a SOAP 1.2 service put its own code directly in Code/Value?
    No. That `Value` is restricted to the five SOAP-defined codes. Application categories go in `Subcode/Value` as QNames, which can nest. In SOAP 1.1, `faultcode` is any QName, and new codes extend the standard ones with dots, as in `Client.Authentication`.
  • Where does a SOAP 1.2 MustUnderstand fault say which header block was not understood?
    In `NotUnderstood` header blocks in the fault message's Header, each with a `qname` attribute naming the block. The node SHOULD provide them and need not list every failing block. SOAP 1.1 defined the `MustUnderstand` code but no structure for this.

saying these in an interview costs you the question

  • SOAP 1.2 still uses faultcode and faultstring, only in a new namespace.
  • A SOAP 1.2 service may put its own error code directly in Code/Value.
  • Client and Server are still valid top-level codes in SOAP 1.2.
  • Clients should branch on the faultstring or Reason text to classify errors.
  • DataEncodingUnknown was already one of SOAP 1.1's fault codes.
  • A SOAP 1.2 Body may carry a Fault next to normal response elements.