In the last blog we discussed successful REST and SOAP requests and responses, but what happens when something goes wrong? In this blog we are going to look at some examples of situations where the output is incorrect or unexpected and how RESTful and SOAP Web Services handle these cases.

REST

Let's take a look at what a REST-style Web Service does for error handling.  

In one of our previous blogs we talked about HTTP response codes, if you aren't familiar with them I highly recommend checking it out. Why might you ask...Well a RESTful service always responds with one of these codes for each request. When successful the most common is 200, which means OK, but any 2XX code can be sent for a successful response. The interesting codes regarding errors happen to be 4XX and 5XX codes, these are the ones sent with there is a problem. Typically a 4XX code is sent when the problem is caused by the client, whether a specified resource cannot be found (404) or whether the server cannot respond to the clients request because it is invalid (400). On the other hand 5XX codes are sent when the server cannot respond to a valid request. This could be caused by something as serious as a database that the server relies on being down or even something as simple as a Null Pointer Exception.

It is important to note that most servlet containers will send a default error message in the Response Body with each code but as the developer you are able to specify custom messages with as much information as you want and in any format you wish, just make sure to document the response formats and error conditions!

Here is an example of what you might see if your request generates a 500 Internal Server Error.  This is the standard message and as you can see it isn't very helpful.

HTTP 1.1/500 Server Error

A better error response might be something like

HTTP 1.1/500 Server Error 
Content-Type: application/json

{"code":500, "message": "Unable to connect to Oracle database"}

or this in the case of a client error.

HTTP 1.1/400 Bad Request

Content-Type: text/xml

<?xml version="1.0" encoding="UTF 8"?>
    <error>
        <code>400</code>
        <message>Missing Required Request Parameter "word"</message>
    </error>
</xml>

SOAP

SOAP requests deal with error conditions in similar ways. Since SOAP requests usually play in the same sandbox that RESTful requests do (HTTP) they can respond with the exact same error codes for the exact same conditions. There are actually only a few small differences. As with all SOAP requests, error responses must be sent in the xml format according to the SOAP specifications. Another difference is that according to the W3 SOAP spec, if an error occurs during processing of a SOAP request the server must respond with an HTTP 500 Internal Server Error code along with a SOAP message describing the error. The message is wrapped in the SOAP envelope and is inside a new SOAP fault element indicating the error. An example SOAP error response is below.

HTTP 1.1/500 Server Error

Content-Type: text/xml

<?xml version="1.0"?>
    <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
        xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/1999/XMLSchema"
        xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
        <SOAP-ENV:Body>
            <SOAP-ENV:Fault>
                <faultcode>SOAP-ENV:Client</faultcode>
                <faultstring>Can’t call “getDefinition” because there are 
                             not enough parameters.</faultstring>
            </SOAP-ENV:Fault>
        </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>
</xml>

It is important to note a few things about this response. The HTTP code is a 500 Internal Server Error according to the SOAP spec, but the faultcode element reports that the error was a client error which in REST would be a 4XX error type. The faultcode element can also contain a SOAP-ENV:Server value. The faultstring element provides a human readable message and is similar to the reason phrased defined by HTTP. There are a few other elements that are defined in the SOAP fault tag and those can be seen in the SOAP specification.

Summary

Whether you are building a RESTful or SOAP based Web Service the key points to take away from general Web Service error handling are:

• Follow the SOAP spec: Odds are your client will be using a SOAP client library which will expect errors to be sent according to the spec. Include the correct faultcode and a good faultstring.
• Use the Correct Machine Readable Response Codes: As the developer you can respond with any response code you choose (even ones that are not in the HTTP spec) but as a rule you should only respond with codes that are correct for the error case according to the HTTP spec, e.g. stick to 4XX for client error, 5XX for server error. Note: A too common thing is to always return a 200 OK and include the error message in the body. This is not a good practice, some clients by default will cache 200 responses for efficiency, and you don't want the client to cache the response to a bad request. Good Example: Twitter, Bad Example: Flickr
• Include Human Readable Messages: Do not rely on the default messages, give the client enough information to correct the request and resend it, or let the client know when the request will be successful.