Appendix A. A Guide to Common Status Codes

This section outlines some of the most common status codes in use in HTTP APIs, their meaning, and some notes about when they can be used.

Code	Meaning	Notes
100	Continue	For a large request, a client can send just the headers and Expect: 100-continue as an additional header. If the 100 status is received in response, the client can then send the request as normal. Think of it as “go ahead”—in fact, many libraries will handle this for you and make the second request without further prompting.
200	OK	This is good news; everything worked as expected.
201	Created	A new resource was created. This is often accompanied by a Location header or a representation of the new resource in the body of the request.
202	Accepted	This is useful if something is taken to be actioned later, such as being placed on a queue for asynchronous processing.
204	No Content	The request was successful, but there is nothing to return. Perhaps this is the result of a DELETE request.
301	Moved Permanently	The content is at a new location, and this is a permanent change. Links to the old URL must be updated, and this change will often be cached for long periods.
302	Found	This is much like a 200, but the content was not at the location specified. Usually this is seen when an application uses rewrite rules.
304	Not Modified	This is sent in response to a request that included information such as an ETag or Last-Modified, which indicates that the resource is cached and specifies which version the client has. This status code means “use the one you have” and is useful to avoid repeatedly transferring large representations that don’t change.
400	Bad Request	This is the general “something went wrong” status. Sometimes there may be no more detail to offer; at other times, you may choose not to transmit anything more.
401	Unauthorized	Credentials are needed in order to access this resource.
403	Forbidden	This contrasts with 401 and means that any credentials given were not sufficient to access this resource.
404	Not Found	A request was made for something the server doesn’t have or doesn’t know how to provide. Alternatively, a request was made for a resource that isn’t available to this user and the 404 doesn’t leak information about the potential existence of such a resource.
405	Method Not Allowed	The verb used to access this URL isn’t supported—this is useful if, for example, you don’t allow updates to a resource but a PUT request was received.
406	Not Acceptable	The server cannot generate a response in accordance with the Accept headers that came with the request.
409	Conflict	There is a mismatch between versions of resources, such as an incoming update when the resource has changed in the meantime.
410	Gone	A resource did exist, but doesn’t any more. Many services will simply return a 404 here, or a 409 may also be appropriate, particularly if something is trying to perform an update on the resource.
415	Unsupported Media Type	The media type specified in the Content-Type header isn’t understood by this server.
429	Too Many Requests	Usually used with rate-limiting schemes, although Twitter uses 420 “Enhance Your Calm” for this purpose.
500	Internal Server Error	An unhandled error occurred, and is the fault of the server rather than the client. In PHP applications, PHP has usually segfaulted, leaving the web server unable to return any useful information.
501	Not Implemented	The server can’t handle this request; it may also indicate that a documented feature is currently still under construction.
502	Bad Gateway	This indicates that a proxy server of some sort has failed, such as a load balancer.
503	Service Unavailable	This is usually seen when a server is temporarily offline, such as during a planned maintenance window. Often, it really means “try again later” but it also discourages caching, and is particularly useful to stop search engines from finding and caching your temporary holding page.

For a full list of status codes, there is an excellent reference on Wikipedia.