Response Status Codes

The most important part of an HTTP response is the response status code. This code is analogous to a summary of the response. It lets the Web client know the basic outcome of the server’s attempt to fulfill the request.

Status codes are grouped into the following ranges:

• Informational (100-199)

• Successful (200-299)

• Redirection (300-399)

• Client error (400-499)

• Server error (500-599)

Informational (100-199)

The status codes in the 100 range are not very common, nor do they provide a crucial function in a typical HTTP transaction. Because these responses are for informational purposes only and thus never contain any content, the response is considered to be terminated by an empty line. Also, because status codes in the 100 range were not defined under HTTP/1.0 or HTTP/0.9, a Web server should not respond with a 100 range response to a Web client identifying itself as using either of these.

100 Continue

The 100 Continue status code is intended to be used in cases where the Web client desires feedback from the Web server prior to receiving the requested resource. The definition attempts to leave the implementation flexible, simply providing this allocation for cases where it might prove useful.

This status code is similar to a conversation between two people, where the person currently listening gives a nod or says something to indicate that he/she is listening, and it is fine to continue speaking.

The way a proxy handles this response is a bit unique. Although it is required that a proxy forward all 100 range responses, it must not forward this response to a Web client that identifies itself as an HTTP/1.0 client, unless the Web client specifically included an Expect request header indicating that it was expecting a 100 Continue response:

Expect: 100-Continue 

This is, in fact, the most common implementation of this feature. The Expect request header, when used in this way, is analogous to saying, “Guess what?”. If the Web server responds with a 100 Continue response, it is basically saying, “What?”. Just as in conversation between two people, this indicates to the person talking that it is appropriate to continue.

101 Switching Protocols

The 101 Switching Protocols response is reserved for the case where the Web client includes an Upgrade general header in the HTTP request. This response indicates to the Web client that the Web server is both accepting the request to upgrade and intending to use the new protocol in all communication that follows this response. The response including the 101 Switching Protocols status code will be sent using whatever protocol was already being used.

Successful (200-299)

The status code most often seen in HTTP responses on the Web is 200 OK, although some may argue that a 404 Not Found is a popular response as well, due to the number of bad links on the Web. The HTTP specification deems all 200-level responses to be a success of some sort. Partially because there are several types of requests, there are also several success messages. According to the definition, each of these specifically indicates that the Web client’s request was received, understood, and accepted by the server.

200 OK

The 200 OK response indicates to the Web client that its request has succeeded. In general, the content that was being requested is contained in the response, whether it is a TRACE request fulfillment, the resource indicated by a GET request, the header returned in a HEAD request, or the resource containing the result of action taken in a POST request.

201 Created

This status code is reserved for any situation in which the Web client’s request requires an entity to be created in order to be fulfilled. In these cases, 201 Created is a successful response. One request that warrants a 201 Created response is a PUT request.

A Location response header is required for this status code, and it contains the absolute URL of the resource that was created.

202 Accepted

The 202 Accepted status code serves the same purpose as 201 Created, except that it is explicitly reserved for cases in which the Web server needs to respond prior to actually creating the entity on the server.

Although the Web client’s request was not explicitly fulfilled yet, the idea is that the Web server does intend to fulfill the request, just at a later date. This is useful for cases whereby batch jobs run at night to fulfill the day’s requests, human intervention is desired for ensuring all requests are safe, or any other case in which a delay of some sort is appropriate.

Unlike 201 Created, this status code does not guarantee that the resource will be created; it simply indicates the intent to fulfill the request. Also, because the location of the resource is unknown prior to its creation, a Location response header is not included.

203 Non-Authoritative Information

Sometimes the resource being requested by the Web client can be fulfilled, just not by the intended source. In these cases, a 203 Non-Authoritative Information status code is appropriate.

This status code is only returned in cases where the status code would otherwise have been 200 OK.

204 No Content

As its name implies, the 204 No Content status code indicates to the Web client that the response to its request does not require any content. It should, of course, include any appropriate headers that relay more information about the lack of content.

The definition explicitly states that Web clients handling a 204 No Content response from the server should not change the document view. Thus, this status code allows for the communication between the Web client and the Web server to take place without the explicit knowledge of the user.

205 Reset Content

Because the 204 No Content status code explicitly states that the Web client should not change the document view after receiving such a response, the HTTP definition provides the 205 Reset Content, which explicitly requires the Web client to reset (refresh) the document view. All other uses and attributes of this status code are the same.

206 Partial Content

For cases when the HTTP request includes a Range request header specifically asking for a resource in part rather in its entirety, the 206 Partial Content status code indicates to the Web client that its request for partial content is being successfully fulfilled. A response with a 206 Partial Content status code will include the partial content that is being requested.

Redirection (300-399)

There are many situations where the Web server wants to inform the client that the resource being requested is located elsewhere. These techniques are generally referred to as protocol-level redirects in order to distinguish them from similar methods used in HTML:

<meta http-equiv=”refresh” content=”0; url=http://httphandbook.org/”> 

Although, theoretically, redirection should serve as a method to point stale links to the correct resource, these methods are most often used when redirection is desired as a normal part of an application. For example, many Web applications use a 300-range response of some sort to redirect the users from a page where content was posted so that any reloads in the browser do not result in the POST request being resent and thus reprocessed.

Most HTTP responses with a status code in the 300-range are required to indicate the new location of the resource in a Location response header.

300 Multiple Choices

When a Web server cannot provide the resource requested but wants to relay alternative resources to the client, it will use a 300 Multiple Choices response. The choices may be provided as the content in the response, or one can be provided in a Location header in the response.

301 Moved Permanently

The 301 Moved Permanently response indicates to the Web client that the resource is available elsewhere, and that it (or any proxy) should use the new resource for all future requests.

The new location for the resource is given in the Location response header, which is required for this status code.

The most common example of this status code is when a URL specified in a request erroneously omits a trailing slash when the resource being requested is a directory index.

For example, if a request is made for http://httphandbook.org/directory instead of the proper URL http://httphandbook.org/directory/, a response similar to the following will be sent:

HTTP/1.1 301 Moved Permanently 
Date: Tue, 21 May 2002 12:34:56 GMT 
Location: http://httphandbook.org/directory/ 
Content-Type: text/html 
Content-Length: 186 

<html> 
<head> 
<title>301 Moved Permanently</title> 
</head> 
<body> 
<h1>Moved Permanently</h1> 
The document has moved 
     <a href=”http://httphandbook.org/directory/”>here</a>. 
</body> 
</html> 

The user is generally unaware that this transaction takes place, because the Web browser will immediately resubmit the HTTP request using the correct URL. At most, an attentive user may notice the URL change in the location bar when the trailing slash is appended.

Although it may seem that this type of transaction would also occur when a request is made for http://httphandbook.org instead of http://httphandbook.org/, this is generally not the case. When no resource is specified by the user, the Web browser will assume document root when making the request. Without a resource, the Web browser would be unable to construct a proper request line.

302 Found

A 302 Found response is similar to the 301 Moved Permanently response, except that the new location should only be used for this request. The new resource location is indicated in a Location header, and the client should issue the same request method for the new resource as it used for the request that resulted in this response.

This response is what many server-side scripting languages such as PHP and ColdFusion currently use when a developer manually uses a Location header in the code (although discussion is underway for PHP to allow the developer to override the response status code). For example:

<? 
header(“Location: http://httphandbook.org/”); 
?> 

This will result in a response similar to the following:

HTTP/1.1 302 Found 
Date: Tue, 21 May 2002 12:34:56 GMT 
Location: http://httphandbook.org/ 
Transfer-Encoding: chunked 
Content-Type: text/html 

0 

303 See Other

The 303 See Other status code is the client’s way to explicitly ask the client to issue a GET request for the resource specified in the Location header. In practice, this status code is handled exactly the same by Web clients as a 302 Found status code, although present implementations of the 302 Found status code are relying on Web clients improperly handling it, as noted in the description of the 302 Found status code.

304 Not Modified

When a client issues a request and includes an If-Modified-Since header, the 304 Not Modified response is, as you might guess, the Web server’s way of letting the client know that the resource has not been modified since the date that the client specified. No content is included in a 304 Not Modified response.

The Web server must also include a Date general header unless it does not have a clock. It will also include an ETag response header and a Content-Location entity header in cases where it would have included these headers in a 200 OK response.

Also, because this type of response is usually sent to caching proxies, a Web server will also include an Expires entity header, a Cache-Control general header, and a Vary response header if these differ from the values the proxy cached.

305 Use Proxy

The HTTP definition reserves a status code for Web servers that want to explicitly force a Web client to use a proxy. When this is the case, the Web server will respond with 305 Use Proxy.

The required Location response header in a 305 Use Proxy response indicates the location of the proxy to be used. It is important to note that this type of response indicates that the use of a proxy is required only for the resource being requested and not necessarily for every resource residing on the current Web server.

306

The 306 status code is deprecated and no longer used.

307 Temporary Redirect

The 307 Temporary Redirect status code was added to the HTTP definition due to the improper handling of the 302 Found status code by nearly all Web clients. This status code is interpreted just as the 302 Found status code was intended to be interpreted. The Web client issues a request to the new location of the resource using the same request method it used in the current transaction (rather than always using GET).

Client Error (400-499)

The 400 range of status codes are reserved for all error conditions in which the fault lies with the client. Careful distinction must be made for status codes such as 404 Not Found because these types of errors seem as if they are not solely the fault of the client. However, each transaction must be viewed independently, much like how a Web server treats each transaction. If a client requests a resource that does not exist, the client is in error, even if it is using an invalid URL due to the HTML previously returned in an HTTP response.

400 Bad Request

The most generic status code for a client error is the 400 Bad Request status code. This is how a Web server responds if you send it a malformed HTTP request. Because most major Web browsers adhere well enough to the HTTP definition to avoid this type of error, you will most likely never encounter it unless you try to communicate directly with a Web server using telnet, or you write your own Web client.

401 Unauthorized

Using HTTP authentication, a Web server’s first response to a request for a protected resource requiring authorization is a 401 Unauthorized response. The WWW-Authenticate response header is included with all HTTP responses with a 401 Unauthorized status code. In most cases, the users are largely unaware that an “error” response was ever received, so long as the users enter the proper credentials, because the Web client will issue the subsequent request with the access information and display the resulting page.

402 Payment Required

Several status codes are included in the HTTP specification in order to make allocations for potential future use. The 402 Payment Required status code is reserved for cases when the resource being requested requires payment. Although there is consistent support for this status code, it is rarely used in practice.

403 Forbidden

A status code of 403 Forbidden indicates to the Web client that the server has reached a permanent error condition and that it cannot fulfill the client’s request due to insufficient privileges. This contrasts with the 401 Unauthorized status code, whereby the client can resubmit the request, with authentication information included, to obtain the resource.

In practice, the 403 Forbidden status code is usually seen after a maximum number of failed attempts at authentication or when a resource being requested cannot be accessed. This status code indicates that either the resource does not exist or that the Web client is not allowed to access it. The definition suggests the use of a 404 Not Found response for cases when you do not want to risk arousing the curiosity of a potential attacker.

404 Not Found

Arguably one of the most recognized status codes in HTTP, the 404 Not Found status code is used to indicate that the resource being requested simply does not exist. Of course, because receiving any response indicates that a Web server was contacted, it can be assumed that the Web server indicated in the URL does exist. In most cases, this error message is displayed to users, so most people who browse the Web are familiar with it.

In fact, 404 is such a recognized HTTP status code that it has crept into hacker jargon. Its entry in the jargon file can be found at the following URL:

http://www.tuxedo.org/~esr/jargon/html/entry/404.html

405 Method Not Allowed

The 405 Method Not Allowed status code alerts the Web client that the request method used in the HTTP request is not supported. The Web server will include valid methods in the response within an Allow header.

406 Not Acceptable

When a Web server receives a demand in an HTTP request in the form of an Accept header or any other in the Accept family (including Accept-Charset, Accept-Encoding, and Accept-Language), it will respond with a 406 Not Acceptable status code when it cannot meet those demands.

The wording of this response can seem confusing, and it is easiest to understand if you consider it to be an admission of guilt on the part of the Web server because it cannot meet the Web client’s demand(s).

407 Proxy Authentication Required

The 407 Proxy Authentication Required status code is used by proxies. The proxy uses this as a response to a Web client without contacting the server of the resource being requested.

In order to indicate how to properly authenticate itself, the proxy will provide the Web client with a Proxy-Authenticate header within this response. The Web client should then submit a second request with a proper Proxy-Authorization header.

408 Request Timeout

When the Web server requires at least one additional HTTP request from the client prior to being capable of sending an appropriate response, the potential timeout condition is handled with a 408 Request Timeout status code. This situation can occur when the Web client neglected to include a Connection: close general header when using HTTP/1.1 but fails to make an additional request.

The Web server closes the connection after sending an HTTP response with a 408 Request Timeout status code.

409 Conflict

The 409 Conflict status code is reserved for conditions when the Web server is unable to fulfill the client’s request due to a conflict with the state of the resource. Such a condition could arise when the resource has changed since the previous required conditions were agreed upon.

The exact description of the conflict should be included in the content of the HTTP response. This tactic, used in many cases, allows for flexibility in the definition, which in turn helps it adapt to new implementations.

410 Gone

In the case in which a resource is no longer available, a 410 Gone status code can be used in the response to indicate a permanent absent condition. In practice, a 404 Not Found is often used in cases where this status code would be more appropriate.

The 410 Gone status code is more appropriate in cases where the Web server recognizes the requested resource as being removed rather than simply being unable to find it.

411 Length Required

In cases where the HTTP request includes content but fails to include a Content-Length entity header as appropriate, the Web server responds with a 411 Length Required status code to indicate the client’s failure to specify the size of the included content.

412 Precondition Failed

In response to a failure of the precondition set forth by the Web client in a request header such as If-Match, the server uses a 412 Precondition Failed status code.

413 Request Entity Too Large

In cases in which the content included in an HTTP request is too large for the Web server to handle, it will use a 413 Request Entity Too large status code in the response.

414 Request-URI Too Long

In cases in which the URL used in the HTTP request is longer than the Web server can handle, it will respond using a 414 Request-URI Too Long status code.

Although the HTTP definition includes the 414 Request-URI Too Long status code, it is not recommended that developers depend on a server properly handling any URI that is greater than 255 characters in length. When a substantial amount of data needs to be sent from the Web client, you should employ the POST method if possible.

415 Unsupported Media Type

The 415 Unsupported Media Type status indicates that the Web server cannot interpret the content part of the HTTP request. The media type used in the content of the HTTP response should be indicated in the Content-Type entity header.

416 Requested Range Not Satisfiable

Because the Range request header allows the Web client to specify any range, whether valid or not, the 416 Requested Range Not Satisfiable status code allows the Web server to respond to out-of-range requests with a sensible error code.

417 Expectation Failed

When the Web client’s demands included in an Expect header cannot be met, the Web server includes a 417 Expectation Failed in the HTTP response.

Server Error (500-599)

In cases in which the Web server can provide a valid HTTP response, but it cannot provide the resource being requested due to a server error of some type, it will use a status code in the 500 range in the response.

Web developers see a status code in the 500 range when they are writing code that interacts with the Web server in some way, such as CGI programming or the development of server-side scripting languages. These types of status codes usually indicate that the Web developer has made an error.

500 Internal Server Error

The most generic server error status code is 500 Internal Server Error. In some cases, the Web server will provide more details about the nature of the error in the content of the response. This is likely the most common status code that a developer creating a CGI script will encounter when things do not go as planned.

501 Not Implemented

The 501 Not Implemented status code indicates that the Web server does not support the request method being used in the HTTP request.

502 Bad Gateway

If an intermediate proxy server receives an invalid response from either a proxy nearer to the origin server or the origin server itself, it will use a 502 Bad Gateway status code in the HTTP response that it sends back to the client or proxy nearer the client.

503 Service Unavailable

For any case in which the Web server is unable to satisfy the request temporarily, it will use a 503 Service Unavailable status code in its response. It can also include a Retry-After header to indicate when the Web client will be able to try the request again and likely receive a successful response.

504 Gateway Timeout

If an intermediate proxy times out while waiting for a response from the Web server, it will send a 504 Gateway Timeout status code in the response to the client.

505 HTTP Version Not Supported

If the version of HTTP indicated in the request is not supported by the Web server, it will respond with a 505 HTTP Version Not Supported status code.