A Guide to Common Status Codes - PHP Web Services (2013)

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.