HTTP Status codes for REST (Web) API

My application for the competition Daj się poznać 2017 will be using a Web API on the server side, to feed the Angular client app with the data.

Today, I want to discuss one very simple, but also very important topic for the APIs accessed over HTTP.

HTTP Status Codes

The reason we will build Web API, is to have a fully standardized service, which will be able to query our database and provide the resources to the customer. Whoever we call a customer. In our case, it will be an Angular app, living in the browser. It could be, however, another service, a mobile app (e.g. native Android application), or even a desktop app.

The idea behind RESTful services is very easy. I will not elaborate on it much here. One thing is very important though. You send a HTTP request to the server, and you get a HTTP response with the result.

When you receive a response, one of the first thing that you want to know, is the status of your request. Is it fine? Did it return the proper result? Or maybe it should not return a result, but just save something on the server side?

This is what we have HTTP Status codes for. I would like to show a minimal set of statuses are crucial for the communication to be easy to follow by the clients.

The list of status codes is quite long, you can check it in many places, for example on wikipedia. The list consists of official status codes, which are listed in the official IANA Register. There are also some additional ones, which are added (as usual) by a specific providers, which are used in their products (e.g. Microsoft and their web server IIS).

The specification distinguishes 5 main types of responses:

1xx: Informational – Request received, continuing process

This part is not very interesting for us, for Web API. It is mean to provide informational data (like HTTP 100 continue). 1xx status codes have not been a part of HTTP/1.0 standard and hence, many servers do not send responses with this status.

2xx: Success – The action was successfully received, understood, and accepted

This is much more interesting, we expect success, no?

Proper response should be attached proper status. What can we do?

HTTP 200 – OK.

Successful request, like a GET call that returns proper results.

//returns HTTP 200
return Ok(video);

HTTP 201 – OK (Created a resource).

The request for entity creation has been completed successfully.

//returns HTTP 201
return Created("UriOfTheContent", video);

HTTP 204 – OK (No content).

The request has been successfully fulfilled, and there is no content to return. For example, when you delete a resource, and there’s no content to return.

//returns HTTP 204
return NoContent();

3xx: Redirection – Further action must be taken in order to complete the request

According to my experience, not used so often in Web APIs.

4xx: Client Error – The request contains bad syntax or cannot be fulfilled

HTTP 400 – Bad Request

For example, the JSON provided by the consumer cannot be parsed.

//returns HTTP 400
return BadRequest();

HTTP 401 – Unauthorized

No, or invalid credentials/authentication details have been provided.

//returns HTTP 401
return Unauthorized();

HTTP 403 – Forbidden

Authentication succeeded, but no permission to the requested resource.

//returns HTTP 403
return Forbid();

HTTP 404 – Not Found

Requested resource doesn’t exist.

//returns HTTP 404
return NotFound();

HTTP 409 – Conflicts

For example, conflict between two simultaneous edits.

//returns HTTP 409
var returnAction = CreatedAtAction("PutVideo", new { id = video.Id }, updatedVideo);
returnAction.StatusCode = StatusCodes.Status409Conflict;
return returnAction;

5xx: Server Error – The server failed to fulfill an apparently valid request

HTTP 500 – Internal Server Error

There’s a problem on the server. Not a fault of the client.

//returns HTTP 500
return StatusCode(StatusCodes.Status500InternalServerError);

Web API Status Code Pages

If you want to have a web page returned upon a request, with the status code information, you could configure a Status Code Pages in your app.

In ASP.NET Core, you need to add in the Startup.cs, in the Configure section, the following line:


Why discuss this?

The status codes are such a simple and intuitive thing, that one could think there’s not much to say about it.

However, you could find a lot of implementations, where it’s not properly used. This generates a lot of headaches for the clients.

An example, which may be very often found in different implementations is that the client requests a resource, and gets HTTP 200 OK status, with content set to NULL.

Having a proper status code makes our service easy to use, which is a win for everybody. Both clients and API provider.

Which other HTTP statuses, which I didn’t mention here, are you using in your APIs on a regular basis? Feel free to share your thoughts in the comments!

Stay tuned.

One thought on “HTTP Status codes for REST (Web) API

  1. Pingback:

Leave a Reply

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