When designing a SOAP 1.2 service's error contract, how should Sender versus Receiver, Subcode and Detail be used so clients can act on a Fault?

## Why the fault is a contract A client cannot handle what it cannot classify. A SOAP Fault is the one place where a service tells its consumers, in a machine-readable form, what went wrong and what they can do about it. A well-designed fault vocabulary lets a client decide without a human: fix the request, wait and try again, escalate, or show a message. A badly designed one forces every consumer to parse prose. SOAP 1.2 gives a fixed skeleton for this, and the design work is in what you hang on it. ## The two classes that drive client behaviour Of SOAP 1.2's five fault codes, three are protocol-level and point at a configuration or capability problem rather than a business one: `env:VersionMismatch` (wrong envelope), `env:MustUnderstand` (a mandatory header block not understood) and `env:DataEncodingUnknown` (an unsupported data encoding). Application errors almost always fall under the other two: | Code | SOAP 1.2's definition | Example | What it tells the client | |---|---|---|---| | `env:Sender` | the message was incorrectly formed or lacked the information needed to succeed | missing credentials, an invalid account number, a field out of range | generally not to resend without change | | `env:Receiver` | processing failed for reasons attributable to processing, not to the message's contents | an upstream system did not respond | the message could succeed if resent later | Two cautions follow from the wording: - **Receiver is not a promise that a resend is harmless.** It says the message could succeed later; it says nothing about whether the first attempt had side effects. Whether a resend is safe depends on whether the operation is idempotent or deduplicated, and how often to retry is a resilience policy outside the fault model. - **Sender is the right class for validation failures.** Reporting a bad input as Receiver invites clients to resend the same bad message. ## Subcodes: the service's vocabulary The top-level `Value` is restricted to the five codes of `env:faultCodeEnum`, so the service's own categories go one level down: - Each `Subcode` holds a `Value` of type `xs:QName` that the application or a feature defines, plus an optional nested `Subcode` for further refinement. - SOAP 1.2 describes the codes as a hierarchy, each level identifying the category in more detail. It sets no limit on depth and expects few levels in practice. - Put the QNames in a namespace the service owns, so they cannot collide with another service's, and treat them as part of the published contract: adding one is a change, renaming one breaks clients. - Keep the subcode consistent with the top-level class: a `CardExpired` subcode belongs under `env:Sender`, an `UpstreamTimeout` under `env:Receiver`. ## Detail: data, not prose - `Detail` carries **application-specific error information**: the field that failed, the limit that was exceeded, a timestamp. Its children are **detail entries**, ordinary elements that can be described by the service's schema. - SOAP 1.2 says the fault codes **provide the context** for `Detail`, and a node MUST understand all the codes in a fault to interpret its `Detail`. Design the two together: a given subcode implies a given detail shape. - In SOAP 1.2 the presence of `Detail` says nothing about which parts of the message were processed. - `Reason/Text` is a human-readable explanation, one per language via `xml:lang`, and is not intended for algorithmic processing. A client that branches on its wording breaks the day someone fixes a typo. ## Where it failed: Node and Role Any node that is not the ultimate receiver MUST include `Node`, the URI of the node that generated the fault; the ultimate receiver MAY include it. `Role` names the role the node was acting in. Together they let a client tell a refusal by an intermediary, such as a gateway enforcing a mandatory header, from a refusal by the service itself, which usually calls for different handling. ## A checklist for a fault contract 1. Classify every error condition as Sender or Receiver by the specification's definitions, not by habit. 2. Define a subcode QName per category clients must distinguish, in the service's namespace. 3. Give each subcode a documented `Detail` shape carrying the data a client needs to act. 4. Write `Reason` text for operators, in the languages consumers need, and never require clients to parse it. 5. Version the vocabulary with the rest of the contract; the service description can declare an operation's faults, and the transport binding decides which HTTP status each code travels with. ## The same contract in SOAP 1.1 SOAP 1.1 uses `Client` and `Server` with the same resend guidance, refines them with **dot notation** such as `Client.Authentication` instead of subcodes, names an intermediary with `faultactor`, and gives `detail` a meaning of its own: it MUST be present when the Body could not be processed, so its absence tells the client the fault was not about the Body.