HTTP Status Codes

Learning objectives#

• Know the five status code families
• Use the common codes correctly
• Return them with IHttpActionResult helpers
• Return a custom code with a body

Explanation#

1xx informational, 2xx success, 3xx redirection, 4xx client error (the request was wrong), 5xx server error (the server failed).

Success: 200 OK (data returned), 201 Created (new resource, with a Location header), 204 No Content (success, nothing to return).

Client errors: 400 Bad Request (invalid input), 401 Unauthorized (not logged in), 403 Forbidden (logged in but not allowed), 404 Not Found, 409 Conflict (clashes with current state, e.g. duplicate email or out of stock).

500 Internal Server Error means an unhandled exception. Clients cannot fix it; you must. Never return details of the exception to the client.

ApiController has helpers: Ok(), Created(), CreatedAtRoute(), BadRequest(), NotFound(), Conflict(), Unauthorized(), InternalServerError(), StatusCode(HttpStatusCode.X) and Content(HttpStatusCode.X, body).

Syntax#

1return Ok(data);                                          // 200
2return CreatedAtRoute("GetOrder", new { id }, order);     // 201
3return StatusCode(HttpStatusCode.NoContent);              // 204
4return BadRequest("Quantity must be at least 1.");        // 400
5return NotFound();                                        // 404
6return Content(HttpStatusCode.Conflict, new { message }); // 409 with a body

Code example: An orders controller that answers precisely#

1using System.Net;
2using System.Web.Http;
3

4public class OrderRequest
5{
6    public int ProductId { get; set; }
7    public int Quantity { get; set; }
8}
9

10[RoutePrefix("api/orders")]
11public class OrdersController : ApiController
12{
13    [HttpGet, Route("{id:int}", Name = "GetOrder")]
14    public IHttpActionResult Get(int id)
15    {
16        if (id <= 0) return BadRequest("Order id must be positive.");     // 400
17        if (id > 5000) return NotFound();                                   // 404
18        return Ok(new { Id = id, Status = "Shipped" });                     // 200
19    }
20

21    [HttpPost, Route("")]
22    public IHttpActionResult Create(OrderRequest request)
23    {
24        if (request == null || request.Quantity <= 0)
25            return BadRequest("Quantity must be at least 1.");              // 400
26

27        if (request.ProductId == 99)
28            return Content(HttpStatusCode.Conflict,
29                new { message = "Product 99 is out of stock." });           // 409
30

31        var id = 1001;
32        return CreatedAtRoute("GetOrder", new { id },
33            new { Id = id, request.ProductId, request.Quantity });          // 201
34    }
35

36    [HttpDelete, Route("{id:int}")]
37    public IHttpActionResult Cancel(int id)
38    {
39        return StatusCode(HttpStatusCode.NoContent);                        // 204
40    }
41}

GET    /api/orders/0                         → 400 {"Message":"Order id must be positive."}
GET    /api/orders/9999                      → 404
POST   /api/orders {"ProductId":99,"Quantity":1} → 409 {"message":"Product 99 is out of stock."}
POST   /api/orders {"ProductId":5,"Quantity":2}  → 201 Location: /api/orders/1001
DELETE /api/orders/1001                      → 204

This example is illustrative. Copy or download it and run it in your own environment; the expected output is shown above.

Step-by-step explanation#

1. Validation failures return 400 with a short message; Web API wraps the string as {"Message": ...}.
2. An id that does not exist returns 404 with no body.
3. A business conflict (no stock) returns 409 with a JSON body explaining why.
4. A successful create returns 201 and a Location header built from the route named GetOrder.
5. A successful delete returns 204: nothing more to say.

Real-world use case#

Common mistakes#

Best practices#

• Return 201 + Location for creates
• Use 409 for business-rule conflicts
• Keep error bodies small and consistent
• Never expose stack traces in responses

Remember this#

Practice exercise#

1using System.Net;
2using System.Web.Http;
3

4public class RegisterRequest { public string Email { get; set; } }
5

6public class RegisterController : ApiController
7{
8    [HttpPost, Route("api/register")]
9    public IHttpActionResult Post(RegisterRequest req)
10    {
11        if (req == null || string.IsNullOrWhiteSpace(req.Email))
12            return BadRequest("Email is required.");
13        if (req.Email == "taken@example.com")
14            return Content(HttpStatusCode.Conflict, new { message = "Email already registered." });
15        return Created("api/users/42", new { Id = 42, req.Email });
16    }
17}

Mini quiz#

Want more? Practise all ASP.NET Web API MCQs · ASP.NET Web API interview questions

Related topics#

My notes#

Saved in this browser.