Treating the HTTP Status code right

If you’ve been following the whole Ajax thing for a while, you’ve certainly seen this few lines of code hundreds of times. You know, the ones that check the readyState and status properties of a xmlHttpRequest.

    if (req.readyState == 4) {
        if (req.status == 200) {
            // ...processing...
        } else {
            alert("There was a problem retrieving the XML data:n");
        }
    }

The status is the HTTP code returned by the web server (here 200, meaning that everything went fine). Normally, the status code is part of the private conversation between the browser and the web server. You don’t have to worry about it, unless of course you encounter the dreaded 404 Page Not Found.

Things change when you start developing Ajax-style with XmlHttpRequest. You are basically by-passing the browser native handling of HTTP and left dealing with the status code on your own. And, that’s a great opportunity. Why ? Because you can
use it to relay information about the execution of your server-side scripts.

The HTTP protocol defines many status codes. For a web developer some of the interesting ones are:

• 200 Ok
• 201 created
• 400 bad request
• 403 forbidden
• 500 internal server error

Most server-side scripting languages will let you modify the http response header and set just about any status code. For instance in PHP, if you were processing a request that looked suspicious (a tempered query string?) you could do:

< ?php
header('HTTP/1.0 400 Bad Request');
die('sorry, the execution failed for some reason..');
?>

If you are processing a login/registration form, you could use header('HTTP/1.0 200 Ok') for a successful login, header('HTTP/1.0 201 Created') if a registration was ok and an account was created, and maybe header('HTTP/1.0 403 Forbidden') for a wrong password or if the username was already taken.

Back to the javascript code, here’s now a smarter response handler for the authentication example.

switch (req.status) {
    case 200:
            // login ok, moving on...
            break;
    case 201:
            // was a registration.. will show a welcome message.
           showWelcomeMessage(req.reponseText);
           break;
    case 403:
           // authentication problem. The error message is in responseText
          showErrorMessage(req.responseText);
          break;
    default:
         // unknown error
         alert("There was a problem..");
    }

Remark: Safari will return a ‘undefined’ status code if the response content is empty, so make sure to have at least a space in the response (using echo "" in PHP for instance).

That’s it! Happy coding in 2006.