Java Web Services

Error Handling with SOAP Faults

SOAP errors are handled using a specialized envelope known as a Fault Envelope. If an error occurs while the server processes a SOAP message, it constructs a SOAP Fault and sends it back to the client. Here’s a typical SOAP 1.1 Fault:

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:
xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/
XMLSchema">

<SOAP-ENV:Body>
    <SOAP-ENV:Fault>
        <faultcode>SOAP-ENV:Server</faultcode>
         <faultstring>Test Fault</faultstring>
         <faultactor>/soap/servlet/rpcrouter</faultactor>
         <detail>
            <stackTrace>[SOAPException: faultCode=SOAP-ENV:Server; msg=Test Fault]
            at StockQuantity.getQty(StockQuantity.java:21)
            at java.lang.reflect.Method.invoke(Native Method)
            at org.apache.soap.server.RPCRouter.invoke(RPCRouter.java:146)
            ...
            at org.apache.tomcat.util.ThreadPool$ControlRunnable.run(
                ThreadPool.java:501)
            at java.lang.Thread.run(Thread.java:498)
         </stackTrace>
         </detail>
     </SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

A SOAP Fault is a special element that must appear as an immediate child of the SOAP body element. The <faultcode> and <faultstring> elements are required. The <faultactor> and <detail> elements are optional. Table 4-1 lists the possible values for the faultcodes and their meanings.

Table 4-1. SOAP faultcodes

Faultcode	Meaning
VersionMismatch	The SOAP node processing the request encountered a version mismatch. ...