Home > Articles

The SOAP Protocol

This chapter is from the book

Faults: Error Handling in SOAP

When something goes wrong in Java, we expect someone to throw an exception; the exception mechanism gives us a common framework with which to deal with problems. The same is true in the SOAP world. When a problem occurs, the SOAP spec provides a well-known way to indicate what has happened: the SOAP fault. Let's look at an example fault message:

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
       xmlns:st="http://www.skatestown.com/ws">
 <env:Header>
  <st:PublicServiceAnnouncement>
   Skatestown's Web services will be unavailable after 5PM today
   for a two hour maintenance window.
  </st:PublicServiceAnnouncement>
 </env:Header>
 <env:Body>
  <env:Fault>
   <env:Code>
    <env:Value>env:Sender</env:Value>
    <env:Subcode>
     <env:Value>st:InvalidPurchaseOrder</env:Value>
    </env:Subcode>
   </env:Code>
   <env:Reason>
    <env:Text xml:lang="en-US">
     Your purchase order did not validate!
    </env:Text>
   </env:Reason>
   <env:Detail>
    <st:LineNumber>9</st:LineNumber>
    <st:ColumnNumber>24</st:ColumnNumber>
   </env:Detail>
  </env:Fault>
 </env:Body>
</env:Envelope>

Structure of a Fault

A SOAP fault message is a normal SOAP message with a single, well-known element inside the body: soapenv:Fault. The presence of that element acts as a signal to processors to indicate something has gone wrong. Of course, just knowing something is wrong is rarely useful enough; you need a structure to help determine what happened so you can either try again with a better idea of what might work or let the user know the problem. SOAP faults have several components to help in this regard.

Fault Code

The fault code is the first place to look, since it tells you in a general sense what the problem was. Fault codes are QNames, and SOAP defines the set of legal codes as follows (each item is the local part of the QName—the namespace is always the SOAP envelope namespace):

  • Sender—The problem was caused by incorrect or missing data from the sender. For instance, if a service required a security header in order to do its work and it was called without one, it would generate a Sender fault. You typically have to make a change to your message before resending it if you hope to be successful.

  • Receiver—Something went wrong on the receiver while processing the message, but it wasn't directly attributable to the message contents. For example, a necessary resource like a database was down, a thread wasn't available, and so on. A message causing a Receiver fault might succeed if resent at a later time.

  • mustUnderstand—This fault code indicates that a header was received that was targeted at the receiving node, marked mustUnderstand="true", and not understood.

  • VersionMismatch—The VersionMismatch code is generated when the namespace on the SOAP envelope that was received isn't compatible with the SOAP version on the receiver. This is the way SOAP handles protocol versioning; we'll talk about it in more detail later.

The fault code resides inside the Code element in the fault, in a subelement called Value. In the example code, you can see the Sender code, meaning something must have been wrong with the request that caused this fault. We have the Value element instead of putting the code qname directly inside the Code element so that we can extend the expressive space of possible fault codes by adding more data inside another element, Subcode.

Subcodes

SOAP 1.2 lets you specify an arbitrary hierarchy of fault subcodes, which provide further detail about what went wrong. The syntax is a little verbose, but it works. Here's an example:

<env:Code>
  <env:Value>env:Sender</env:Value>
  <env:Subcode>
   <env:Value>st:InvalidPurchaseOrder</env:Value>
  </env:Subcode>
</env:Code>

The Code element contains an optional Subcode element. Just as Code contains a mandatory Value, so too does each Subcode—and each Subcode may contain another Subcode, to whatever level of nesting is desired. Generally the hierarchy won't go more than about three levels deep. In our example, the subcode tells us that the problem was an invalid purchase order.

Reason

The Reason element, also required, contains one or more human-readable descriptions of the fault condition. Typically, the reason text might appear in a dialog box that alerts the user of a problem, or it might be written into a log file. The Text element contains the text and there can be one or more such messages. Why would you have more than one? In the increasingly international environment of the Web, you might wish to send the fault description in several languages, as in this example from the SOAP primer:

   <env:Reason>
   <env:Text xml:lang="en-US">Processing error</env:Text>
   <env:Text xml:lang="cs">Chyba zpracování</env:Text>
   </env:Reason>

The spec states that if you have multiple Text elements, you should have a different value for xml:lang in each one—otherwise you might confuse the software that's trying to print out a single coherent message in a given language.

Node and Role

The optional Node element, not shown in our example, tells us which SOAP node (the sender, an intermediary, or the ultimate destination) was processing the message at the time the fault occurred. It contains a URI.

The Role element tells which role the faulting node was playing when the fault occurred. It contains a URI that has exactly the same semantics, and the same values, as the role attribute we described when we were talking about headers. Note the difference between this element and NodeNode tells you which SOAP node generated the fault, and Role tells what part that node was playing when it happened. The Role element is also optional.

Fault Details

We have a custom fault code and a fault message, both of which can tell a user or software something about the problem; but in many cases, we would also like to pass back some more complex machine-readable data. For example, you might want to include a stack trace while you're developing services to aid with debugging (though you likely wouldn't do this in a production application, since stack traces can sometimes give away information that might be useful to someone trying to compromise your system).

You can place anything you want inside the SOAP fault's Detail element. In our example at the beginning of the section, the line number and column number where the validation error occurred are expressed, so that automated tools might be able to help the user or developer to fix the structure of the transmitted message.

SOAP 1.1 Difference: Handling Faults

Faults in SOAP 1.2 got an overhaul from SOAP 1.1's version. All the subelements of the SOAP Fault element in SOAP 1.1 are unqualified (in no namespace). The Fault subelements in SOAP 1.2 are in the envelope namespace.

In SOAP 1.1, there is no Subcode, only a single faultcode element. The SOAP 1.1 fault code is a QName, but its hierarchy is achieved through dots rather than explicit structure—in other words, whereas in SOAP 1.1 you might have seen

<faultcode>env:Sender.Authorization.BadPassword</faultcode>
in SOAP 1.2 you see something like:
<env:Code>
 <env:Value>env:Sender</env:Value>
 <env:Subcode>
  <env:Value>myNS:Authorization</env:Value>
  <env:Subcode>
   <env:Value>myNS:BadPassword</env:Value>
  </env:Subcode>
 </env:Subcode>
</env:Code>

The env:Reason element in SOAP 1.2 is called faultstring in SOAP 1.1. Also, 1.1 only allows a single string inside faultstring, whereas 1.2 allows different env:Text elements inside env:Reason to account for different languages.

The Client fault code from 1.1 is now Sender, which is less prone to interpretation. Similarly, 1.1's Server fault code is now Receiver.

In SOAP 1.1, the detail element is used only for information pertaining to faults generated when processing the SOAP body. If a fault is generated when processing a header, any machine-readable information about the fault must travel in headers on the fault message. The reasoning for this went something like this: Headers exist so that SOAP can support orthogonal extensibility; that means you want a given message to be able to carry several extensions that might not have been designed by the same people and might have no knowledge of each other. If problems occurred that caused each of these extensions to want to pass back data, they might have to fight for the detail element. The problem with this logic is that the detail element isn't a contended resource, in the same way the soapenv:Header isn't a contended resource. If multiple extensions want to drop their own elements into detail, that works just as well as putting their own headers into the envelope. So this restriction was dropped in SOAP 1.2, and env:Detail can contain anything your application desires—but the rule still must be followed for SOAP 1.1.

SOAP 1.2 introduces the NotUnderstood header and the Upgrade header, both of which exist in order to clarify what went wrong with particular faults (mustUnderstand and VersionMismatch) in a standard way.

Using Headers in Faults

Since a fault is also a SOAP message, it can carry SOAP headers as well as the fault structure. In our example at the beginning of this section, you can see that SkatesTown has included a public service announcement header. This optional information lets anyone who cares know that the Web services will be down for maintenance; and since it isn't marked mustUnderstand, it doesn't affect the processing of the fault message in any way. SOAP defines some headers specifically for use in faults.

The NotUnderstood Header

You'll recall that SOAP processors are forced to fault if they encounter a mustUnderstand header that they should process but don't understand. It's great to know something wasn't understood, but it's more useful if you have an indication of which header was the cause of the problem. That way you might be able to try again with a different message if the situation warrants. For example, let's say a message was sent with a routing header marked mustUnderstand="true". The purpose of the routing header is to let the service know that after it finishes processing the message, it's supposed to send a copy to an endpoint whose address is in the contents of the header (probably for logging purposes). If the receiver doesn't understand the header, it sends back a mustUnderstand fault. The sender might then, for instance, ask the user if they would still like to send the message, but without the carbon-copy functionality. If the routing header is the only one in the envelope, then it's easy to know which header the mustUnderstand fault refers to. But what if there are multiple mustUnderstand headers?

SOAP 1.2 introduced a NotUnderstood header to deal with this issue. When sending back a mustUnderstand fault, SOAP endpoints should include a NotUnderstood header for each header in the original message that was not understood. The NotUnderstood header (in the SOAP envelope namespace) has a qname attribute containing the QName of the header that wasn't understood. For example:

<env:Envelope xmlns:env='http://www.w3.org/2003/05/soap-envelope'>
 <env:Header>
  <abc:Extension1
    xmlns:abc='http://example.org/2001/06/ext'
    env:mustUnderstand='true'/>
  <def:Extension2
    xmlns:def='http://example.com/stuff'
    env:mustUnderstand='true' />
 </env:Header>
 <env:Body>
  . . .
 </env:Body>
</env:Envelope>

If a processor received this message and didn't understand Extension1 but did understand Extension2, it would return a fault like this:

<env:Envelope
 xmlns:env='http://www.w3.org/2003/05/soap-envelope'
 xmlns:xml='http://www.w3.org/XML/1998/namespace'>
 <env:Header>
 <env:NotUnderstood qname='abc:Extension1'
    xmlns:abc='http://example.org/2001/06/ext' />
 </env:Header>
 <env:Body>
 <env:Fault>
 <env:Code>
  <env:Value>env:mustUnderstand</env:Value>
 </env:Code>
  <env:Reason>
   <env:Text xml:lang='en'>One or more mandatory 
    SOAP header blocks not understood
   </env:Text>
  </env:Reason>
 </env:Fault>
 </env:Body>
</env:Envelope>

This information is handy when you're trying to use the SOAP extensibility mechanism to negotiate QoS or policy agreements between communicating parties.

The Upgrade Header

Back in the section on versioning, we mentioned the Upgrade header, which SOAP 1.2 defines as a standard mechanism for indicating which versions of SOAP are supported by a node generating a VersionMismatch fault. This section fully defines this header.

An Upgrade header (which actually is a misnomer—it doesn't always imply an upgrade in terms of using a more recent version of the protocol) looks like this in context:

<?xml version="1.0" ?>
<env:Envelope
  xmlns:env="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xml="http://www.w3.org/XML/1998/namespace">
 <env:Header>
 <env:Upgrade>
  <env:SupportedEnvelope qname="ns1:Envelope" 
  xmlns:ns1="http://www.w3.org/2003/05/soap-envelope"/>
  <env:SupportedEnvelope qname="ns2:Envelope" 
  xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"/>
 </env:Upgrade>
 </env:Header>
 <env:Body>
 <env:Fault>
  <env:Code>
  <env:Value>env:VersionMismatch</env:Value>
  </env:Code>
  <env:Reason>
  <env:Text xml:lang="en">Version Mismatch</env:Text>
  </env:Reason>
 </env:Fault>
 </env:Body>
</env:Envelope>

This fault would be generated by a node that supports both SOAP 1.1 and SOAP 1.2, in response to some envelope in another namespace. The Upgrade header, in the SOAP envelope namespace, contains one or more SupportedEnvelope elements, each of which indicates the QName of a supported envelope element. The SupportedEnvelope elements are ordered by preference, from most preferred to least. Therefore, the previous fault indicates that although this node supports both SOAP 1.1 and 1.2, 1.2 is preferred.

All the VersionMismatch faults we've shown so far use SOAP 1.2. However, if a SOAP 1.1 node doesn't understand SOAP 1.2, it won't be able to parse a SOAP 1.2 fault. As such, SOAP 1.2 specifies rules for responding to SOAP 1.1 messages from a node that only supports SOAP 1.2. It's suggested that such nodes recognize the SOAP 1.1 namespace and respond with a SOAP 1.1 version mismatch fault containing an Upgrade header as specified earlier. That way, nodes that have the capability to switch to SOAP 1.2 will know to do so, and nodes that can't do so will still be able to understand the fault as a versioning problem.

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.

Overview


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information


To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.

Surveys

Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites, develop new products and services, conduct educational research and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.

Newsletters

If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email information@informit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information


Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.

Security


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.

Children


This site is not directed to children under the age of 13.

Marketing


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information


If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.

Choice/Opt-out


Users can always make an informed choice as to whether they should proceed with certain services offered by InformIT. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.informit.com/u.aspx.

Sale of Personal Information


Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents


California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure


Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.

Links


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact


Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice


We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020