Recipe 13.5 Handling Web Server Errors

Problem

You have obtained a response from a web server and you want to make sure that there were no errors in processing the initial request, such as failing to connect, being redirected, timing out, or failing to validate a certificate. You don't want to have to catch all of the different response codes available.

Solution

Check the StatusCode property of the HttpWebResponse class to determine what category of status this StatusCode falls into, and return an enumeration value (ResponseCategories) representing the category. This technique will allow you to use a broader approach to dealing with response codes.

public static ResponseCategories VerifyResponse(HttpWebResponse httpResponse)
{
    // Just in case there are more success codes defined in the future
    // by HttpStatusCode, we will check here for the "success" ranges
    // instead of using the HttpStatusCode enum as it overloads some
    // values
    int statusCode = (int)httpResponse.StatusCode;
    if((statusCode >= 100)&& (statusCode <= 199))
    {
        return ResponseCategories.Informational;
    }
    else if((statusCode >= 200)&& (statusCode <= 299))
    {
        return ResponseCategories.Success;
    }
    else if((statusCode >= 300)&& (statusCode <= 399))
    {
        return ResponseCategories.Redirected;
    }
    else if((statusCode >= 400)&& (statusCode <= 499))
    {
        return ResponseCategories.ClientError;
    }
    else if((statusCode >= 500)&& (statusCode <= 599))
    {
        return ResponseCategories.ServerError;
    }
    return ResponseCategories.Unknown;
}

The ResponseCategories enumeration is defined like this:

public enum ResponseCategories
{
    Unknown = 0,        // unknown code  ( < 100 or > 599)
    Informational = 1,  // informational codes (100 <= 199)
    Success = 2,        // success codes (200 <= 299)
    Redirected = 3,     // redirection code (300 <= 399)
    ClientError = 4,    // client error code (400 <= 499)
    ServerError = 5     // server error code (500 <= 599)
}

Discussion

There are five different categories of status codes on a response in HTTP:

Category	Available range	HttpStatusCode defined range
Informational	100-199	100-101
Successful	200-299	200-206
Redirection	300-399	300-307
Client Error	400-499	400-417
Server Error	500-599	500-505

Each of the status codes defined by Microsoft in the .NET Framework is assigned an enumeration value in the HttpStatusCode enumeration. These status codes reflect what can happen when a request is submitted. The web server is free to return a status code in the available range even if it is not currently defined for most commercial web servers. The defined status codes are listed in RFC 2616—Section 10 for HTTP/1.1.

We are trying to figure out the broad category of the status of the request. This is achieved where the code inspects the HttpResponse.StatusCode property, compares it to the defined status code ranges for HTTP, and returns the appropriate ResponseCategories value.

When dealing with HttpStatusCode, you will notice that there are certain HttpStatusCode flags that map to the same status code value. An example of this is HttpStatusCode.Ambiguous and HttpStatusCode.MultipleChoices, which both map to HTTP status code 300. If you try to use both of these in a switch statement on the HttpStatusCode, you will get the following error because the C# compiler cannot tell the difference:

error CS0152: The label 'case 300:' already occurs in this switch statement.

See Also

See HTTP: The Definitive Guide by David Gourley and Brian Totty (O'Reilly); see the "HttpStatusCode Enumeration" topic in the MSDN documentation. Also see HTTP/1.1 RFC 2616—Section 10 Status Codes: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html