HTTP Response Codes

The HTTP Specification defines a large number of status classes that should be returned as part of the response. The most common of these are:

  • 200 OK – The request succeeded; The body contains detailed data.
  • 401 Unauthorized – The client did not provide valid login credentials.
  • 403 Forbidden – The client does not have access to the requested resource.
  • 404 Not Found – The requested resource could not be found or does not exist.
  • 409 Conflict – The resource you attempted to create already exists in the system.
  • 500 Internal Server Error – The server experienced an error.

The full list of HTTP response codes can be found on the W3C site, though you may find the Wikipedia entry for HTTP Error Codes more informative.

In all cases, the server should return the HTTP response code appropriate to the response. If further details are needed or custom error codes are required, they should be included in the body of the response and the HTTP response code should be viewed by the client as a “general” class of error. For example, if a client application attempts to add a new Product with a SKU that is already in the system, the full response from the server may resemble:

409 Conflict

“error” {
	“internal_code”: 40896,
	“error_message”: “Our system already recognizes a product with the provided SKU. If you believe this is an error, please contact our support team.”

There do exist some limited client environments that are only able to handle 200 and 404 errors, Adobe’s Flash ActionScript language being the most common. If the API must support these clients, a separate parameter should be introduced to indicate that the server should only return those two responses and embed the detailed errors within the body of the response. In this example, that parameter is named “lerror” for “limited error” and must be set to 1 to only return the 200 and 404 responses:


Please note that using the parameter to limit errors means the default should always be to return the full set of response codes.


Leave a Reply

Your email address will not be published. Required fields are marked *