It is the error report every developer hates to get: "I tried your service and it doesn't work," accompanied by no further explanation. Well, I can't help you with that user, but I can suggest that there is useful information to be culled from careful examination of error messages.
The most important distinction for our purposes is between client errors and server errors.
Assuming you have a service which receives a GET request for a resource specifying HTTP/1.1, the first line of a response which succeeded looks like:
HTTP/1.1 200 OK
This "Status-Line" is composed of three parts, the protocol version, the "Status-Code" and a "Reason Phrase." The protocol and code are used by client software but the phrase is there only to assist human developers.
REST and HTTP Response Status Codes
In contrast to SOAP services, where the response is expected to be a SOAP XML formatted body containing either a successful result or error information according to the SOAP standard, RESTful service clients could be expecting any sort of content so there is no standard error message body. RESTful style requires the use of the standard HTTP Status code values to comunicate the status of a response. As of HTTP 1.1, these codes fall into 5 logical groups as follows:
- 100-1xx Information about a continuing process.
- 200-2xx Success
- 300-3xx Redirecting
- 400-4xx Client request error
- 500-5xx Server error
The most important distinction for our purposes is between client errors and server errors. Trying to debug service code when the real error is due to the way the client request was formatted is obviously a distraction and waste of time. Unfortunately, there are some circumstances in which you may get a 400 series error due not to the client request but a real server error. Here are some of the commonly seen client error codes, with the HTTP1.1 standard interpretation and likely causes:
- 400 Bad Request Something was so wrong with the formatting of the request that the server could not process it. If the service can't come up with a more informative code, this is the default, but there may be more details in the body. For example, the Amazon S3 (Simple Storage System) I used in this RESTful example has an extensive set of error response messages that will be sent as XML. Whether or not your client will see the more detailed message may depend on browser settings.
- 403 Forbidden Access to the service is denied for some reason such as authentication failure.
- 404 Not Found Typically you get this if the service is unable to map the request URL to a resource. Either the URL is incorrect or the service container is unable to start the application.
- 405 Method Not Allowed For example an attempt to use the DELETE method with a service that does not support it.
If the client request is correctly addressed and actually gets through to the service, you might get one of the following. Having only two possible status codes doesn't give you a lot of help, but at least you know the client request got through to the server. If you are lucky, there will be a more informative log entry.
- 500 Internal Server Error There may be additional information in the response headers or body, but browser setting may prevent this information from being shown.
- 503 Service Unavailable This response implies that the problem may be due to a temporary overload and the client can try again.
Note that the service may be returning a 500 code for a variety of reasons. RESTful service frameworks such as Jersey provide extensive error reporting options but there is absolutely no standardization in this area. In the default case a client browser may get a confusing stack trace.
Error Message Handlers
Adding to the possible confusion, some browsers such as MS Explorer have a "Show friendly HTTP error messages" option. When this setting is on, the actual error message, or a potentially useful stack trace generated by the server may not be shown.
If you are writing custom client software for a RESTful service, it should recognize that an error code implies that the response Content-Type header should be checked. For example, the Amazon S3 service sends detailed error messages in XML format with Content-Type: application/xml.
Although practically all SOAP services use HTTP transport, the standard is designed to be used with any message exchanging protocol. As with RESTful services, the most important distinction is between errors which prevent the request from reaching the service and errors generated by the service. Because your SOAP client using HTTP is expecting a well formed XML document, it may well choke on an error message from the server which has been formatted as an HTML, text, or non-SOAP XML response body. Another possibility to watch out for is a client software error report which looks like an error from the service but is actually an error in creating the SOAP request.
The developers of the SOAP standard put a lot of work into defining error reporting so if you get a SOAP fault response, it should be pretty helpful. A SOAP service must return a message body containing a single "Fault" Element which in turn contains detail elements. In addition to a "Reason" element which is (hopefully) human readable, there can be any number of elements from a defined vocabulary of machine readable causes.
This was first published in September 2010