PHP Web Services (2013)
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 specified 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.