HTTP: The Definitive Guide
3.4 Status Codes
HTTP status codes are classified into five broad categories, as shown earlier in Table 3-2 . This section summarizes the HTTP status codes for each of the five classes.
The status codes provide an easy way for clients to understand the results of their transactions. In this section, we also list example reason phrases, though there is no real guidance on the exact text for reason phrases. We include the recommended reason phrases from the HTTP/1.1 specification.
3.4.1 100-199: Informational Status Codes
HTTP/1.1 introduced the informational status codes to the protocol. They are relatively new and subject to a bit of controversy about their complexity and perceived value. Table 3-6 lists the defined informational status codes.
Table 3-6. Informational status codes and reason phrases
| ||
| Status code | Reason phrase | Meaning |
| 100 | Continue | Indicates that an initial part of the request was received and the client should continue. After sending this, the server must respond after receiving the request. See the Expect header in Appendix C for more information. |
| 101 | Switching Protocols | Indicates that the server is changing protocols, as specified by the client, to one listed in the Upgrade header. |
The 100 Continue status code, in particular, is a bit confusing. It's intended to optimize the case where an HTTP client application has an entity body to send to a server but wants to check that the server will accept the entity before it sends it. We discuss it here in a bit more detail (how it interacts with clients, servers, and proxies) because it tends to confuse HTTP programmers.
3.4.1.1 Clients and 100 Continue
If a client is sending an entity to a server and is willing to wait for a 100 Continue response before it sends the entity, the client needs to send an Expect request header (see Appendix C ) with the value 100-continue. If the client is not sending an entity, it shouldn't send a 100-continue Expect header, because this will only confuse the server into thinking that the client might be sending an entity.
100-continue, in many ways, is an optimization. A client application should really use 100-continue only to avoid sending a server a large entity that the server will not be able to handle or use.
Because of the initial confusion around the 100 Continue status (and given some of the older implementations out there), clients that send an Expect header for 100-continue should not wait forever for the server to send a 100 Continue response. After some timeout, the client should just send the entity.
In practice, client implementors also should be prepared to deal with unexpected 100 Continue responses (annoying, but true). Some errant HTTP applications send this code inappropriately.
3.4.1.2 Servers and 100 Continue
If a server receives a request with the Expect header and 100-continue value, it should respond with either the 100 Continue response or an error code (see Table 3-9 ). Servers should never send a 100 Continue status code to clients that do not send the 100-continue expectation. However, as we noted above, some errant servers do this.
If for some reason the server receives some (or all) of the entity before it has had a chance to send a 100 Continue response, it does not need to send this status code, because the client already has decided to continue. When the server is done reading the request, however, it still needs to send a final status code for the request (it can just skip the 100 Continue status).
Finally, if a server receives a request with a 100-continue expectation and it decides to end the request before it has read the entity body (e.g., because an error has occurred), it should not just send a response and close the connection, as this can prevent the client from receiving the response (see Section 4.7.4.2 ).
3.4.1.3 Proxies and 100 Continue
A proxy that receives from a client a request that contains the 100-continue expectation needs to do a few things. If the proxy either knows that the next -hop server (discussed in Chapter 6 ) is HTTP/1.1-compliant or does not know what version the next-hop server is compliant with, it should forward the request with the Expect header in it. If it knows that the next-hop server is compliant with a version of HTTP earlier than 1.1, it should respond with the 417 Expectation Failed error.
If a proxy decides to include an Expect header and 100-continue value in its request on behalf of a client that is compliant with HTTP/1.0 or earlier, it should not forward the 100 Continue response (if it receives one from the server) to the client, because the client won't know what to make of it.
It can pay for proxies to maintain some state about next-hop servers and the versions of HTTP they support (at least for servers that have received recent requests), so they can better handle requests received with a 100-continue expectation.
3.4.2 200-299: Success Status Codes
When clients make requests, the requests usually are successful. Servers have an array of status codes to indicate success, matched up with different types of requests. Table 3-7 lists the defined success status codes.
Table 3-7. Success status codes and reason phrases
| ||
| Status code | Reason phrase | Meaning |
| 200 | OK | Request is okay, entity body contains requested resource. |
| 201 | Created | For requests that create server objects (e.g., PUT). The entity body of the response should contain the various URLs for referencing the created resource, with the Location header containing the most specific reference. See Table 3-21 for more on the Location header. The server must have created the object prior to sending this status code. |
| 202 | Accepted | The request was accepted, but the server has not yet performed any action with it. There are no guarantees that the server will complete the request; this just means that the request looked valid when accepted. The server should include an entity body with a description indicating the status of the request and possibly an estimate for when it will be completed (or a pointer to where this information can be obtained). |
| 203 | Non-Authoritative Information | The information contained in the entity headers (see Section 3.5.4 for more information on entity headers) came not from the origin server but from a copy of the resource. This could happen if an intermediary had a copy of a resource but could not or did not validate the meta-information (headers) it sent about the resource. This response code is not required to be used; it is an option for applications that have a response that would be a 200 status if the entity headers had come from the origin server. |
| 204 | No Content | The response message contains headers and a status line, but no entity body. Primarily used to update browsers without having them move to a new document (e.g., refreshing a form page). |
| 205 | Reset Content | Another code primarily for browsers. Tells the browser to clear any HTML form elements on the current page. |
| 206 | Partial Content | A partial or range request was successful. Later, we will see that clients can request part or a range of a document by using special headersthis status code indicates that the range request was successful. See Section 15.9 for more on the Range header. A 206 response must include a Content-Range, Date, and either ETag or Content-Location header. |
3.4.3 300-399: Redirection Status Codes
The redirection status codes either tell clients to use alternate locations for the resources they're interested in or provide an alternate response instead of the content. If a resource has moved, a redirection status code and an optional Location header can be sent to tell the client that the resource has moved and where it can now be found (see Figure 3-14 ). This allows browsers to go to the new location transparently , without bothering their human users.
Figure 3-14. Redirected request to new location
Some of the redirection status codes can be used to validate an application's local copy of a resource with the origin server. For example, an HTTP application can check if the local copy of its resource is still up-to-date or if the resource has been modified on the origin server. Figure 3-15 shows an example of this. The client sends a special If-Modified-Since header saying to get the document only if it has been modified since October 1997. The document has not changed since this date, so the server replies with a 304 status code instead of the contents.
Figure 3-15. Request redirected to use local copy
In general, it's good practice for responses to non-HEAD requests that include a redirection status code to include an entity with a description and links to the redirected URL(s)see the first response message in Figure 3-14 . Table 3-8 lists the defined redirection status codes.
Table 3-8. Redirection status codes and reason phrases
| ||
| Status code | Reason phrase | Meaning |
| 300 | Multiple Choices | Returned when a client has requested a URL that actually refers to multiple resources, such as a server hosting an English and French version of an HTML document. This code is returned along with a list of options; the user can then select which one he wants. See Chapter 17 for more on clients negotiating when there are multiple versions. The server can include the preferred URL in the Location header. |
| 301 | Moved Permanently | Used when the requested URL has been moved. The response should contain in the Location header the URL where the resource now resides. |
| 302 | Found | Like the 301 status code; however, the client should use the URL given in the Location header to locate the resource temporarily. Future requests should use the old URL. |
| 303 | See Other | Used to tell the client that the resource should be fetched using a different URL. This new URL is in the Location header of the response message. Its main purpose is to allow responses to POST requests to direct a client to a resource. |
| 304 | Not Modified | Clients can make their requests conditional by the request headers they include. See Chapter 3 for more on conditional headers. If a client makes a conditional request, such as a GET if the resource has not been changed recently, this code is used to indicate that the resource has not changed. Responses with this status code should not contain an entity body. |
| 305 | Use Proxy | Used to indicate that the resource must be accessed through a proxy; the location of the proxy is given in the Location header. It's important that clients interpret this response relative to a specific resource and do not assume that this proxy should be used for all requests or even all requests to the server holding the requested resource. This could lead to broken behavior if the proxy mistakenly interfered with a request, and it poses a security hole. |
| 306 | (Unused) | Not currently used. |
| 307 | Temporary Redirect | Like the 301 status code; however, the client should use the URL given in the Location header to locate the resource temporarily. Future requests should use the old URL. |
From Table 3-8 , you may have noticed a bit of overlap between the 302, 303, and 307 status codes. There is some nuance to how these status codes are used, most of which stems from differences in the ways that HTTP/1.0 and HTTP/1.1 applications treat these status codes.
When an HTTP/1.0 client makes a POST request and receives a 302 redirect status code in response, it will follow the redirect URL in the Location header with a GET request to that URL (instead of making a POST request, as it did in the original request).
HTTP/1.0 servers expect HTTP/1.0 clients to do thiswhen an HTTP/1.0 server sends a 302 status code after receiving a POST request from an HTTP/1.0 client, the server expects that client to follow the redirect with a GET request to the redirected URL.
The confusion comes in with HTTP/1.1. The HTTP/1.1 specification uses the 303 status code to get this same behavior (servers send the 303 status code to redirect a client's POST request to be followed with a GET request).
To get around the confusion, the HTTP/1.1 specification says to use the 307 status code in place of the 302 status code for temporary redirects to HTTP/1.1 clients. Servers can then save the 302 status code for use with HTTP/1.0 clients.
What this all boils down to is that servers need to check a client's HTTP version to properly select which redirect status code to send in a redirect response.
3.4.4 400-499: Client Error Status Codes
Sometimes a client sends something that a server just can't handle, such as a badly formed request message or, most often, a request for a URL that does not exist.
We've all seen the infamous 404 Not Found error code while browsingthis is just the server telling us that we have requested a resource about which it knows nothing.
Many of the client errors are dealt with by your browser, without it ever bothering you. A few, like 404, might still pass through. Table 3-9 shows the various client error status codes.
Table 3-9. Client error status codes and reason phrases
| ||
| Status code | Reason phrase | Meaning |
| 400 | Bad Request | Used to tell the client that it has sent a malformed request. |
| 401 | Unauthorized | Returned along with appropriate headers that ask the client to authenticate itself before it can gain access to the resource. See Section 12.1 for more on authentication. |
| 402 | Payment Required | Currently this status code is not used, but it has been set aside for future use. |
| 403 | Forbidden | Used to indicate that the request was refused by the server. If the server wants to indicate why the request was denied , it can include an entity body describing the reason. However, this code usually is used when the server does not want to reveal the reason for the refusal. |
| 404 | Not Found | Used to indicate that the server cannot find the requested URL. Often, an entity is included for the client application to display to the user. |
| 405 | Method Not Allowed | Used when a request is made with a method that is not supported for the requested URL. The Allow header should be included in the response to tell the client what methods are allowed on the requested resource. See Section 3.5.4 for more on the Allow header. |
| 406 | Not Acceptable | Clients can specify parameters about what types of entities they are willing to accept. This code is used when the server has no resource matching the URL that is acceptable for the client. Often, servers include headers that allow the client to figure out why the request could not be satisfied. See Chapter 17 for more information. |
| 407 | Proxy Authentication Required | Like the 401 status code, but used for proxy servers that require authentication for a resource. |
| 408 | Request Timeout | If a client takes too long to complete its request, a server can send back this status code and close down the connection. The length of this timeout varies from server to server but generally is long enough to accommodate any legitimate request. |
| 409 | Conflict | Used to indicate some conflict that the request may be causing on a resource. Servers might send this code when they fear that a request could cause a conflict. The response should contain a body describing the conflict. |
| 410 | Gone | Similar to 404, except that the server once held the resource. Used mostly for web site maintenance, so a server's administrator can notify clients when a resource has been removed. |
| 411 | Length Required | Used when the server requires a Content-Length header in the request message. See Section 3.5.4.1 for more on the Content-Length header. |
| 412 | Precondition Failed | Used if a client makes a conditional request and one of the conditions fails. Conditional requests occur when a client includes an Expect header. See Expect for more on the Expect header. |
| 413 | Request Entity Too Large | Used when a client sends an entity body that is larger than the server can or wants to process. |
| 414 | Request URI Too Long | Used when a client sends a request with a request URL that is larger than the server can or wants to process. |
| 415 | Unsupported Media Type | Used when a client sends an entity of a content type that the server does not understand or support. |
| 416 | Requested Range Not Satisfiable | Used when the request message requested a range of a given resource and that range either was invalid or could not be met. |
| 417 | Expectation Failed | Used when the request contained an expectation in the Expect request header that the server could not satisfy . See Expect for more on the Expect header. A proxy or other intermediary application can send this response code if it has unambiguous evidence that the origin server will generate a failed expectation for the request. |
3.4.5 500-599: Server Error Status Codes
Sometimes a client sends a valid request, but the server itself has an error. This could be a client running into a limitation of the server or an error in one of the server's subcomponents, such as a gateway resource.
Proxies often run into problems when trying to talk to servers on a client's behalf. Proxies issue 5XX server error status codes to describe the problem ( Chapter 6 covers this in detail). Table 3-10 lists the defined server error status codes.
Table 3-10. Server error status codes and reason phrases
| ||
| Status code | Reason phrase | Meaning |
| 500 | Internal Server Error | Used when the server encounters an error that prevents it from servicing the request. |
| 501 | Not Implemented | Used when a client makes a request that is beyond the server's capabilities (e.g., using a request method that the server does not support). |
| 502 | Bad Gateway | Used when a server acting as a proxy or gateway encounters a bogus response from the next link in the request response chain (e.g., if it is unable to connect to its parent gateway). |
| 503 | Service Unavailable | Used to indicate that the server currently cannot service the request but will be able to in the future. If the server knows when the resource will become available, it can include a Retry-After header in the response. See Section 3.5.3 for more on the Retry-After header. |
| 504 | Gateway Timeout | Similar to status code 408, except that the response is coming from a gateway or proxy that has timed out waiting for a response to its request from another server. |
| 505 | HTTP Version Not Supported | Used when a server receives a request in a version of the protocol that it can't or won't support. Some server applications elect not to support older versions of the protocol. |