HTTP Status Codes Every ASP.NET Core Developer Should Know

HTTP Status Codes in ASP.NET Core Web API

What is an HTTP status code?

An HTTP status code is a three-digit number in the API response. It tells the client what happened to its request.

For example, a client sends:

GET /api/products/10

The API might respond with:

• 200 OK — Product 10 was found.

• 404 Not Found — Product 10 does not exist.

• 500 Internal Server Error — The server encountered an unexpected error.

The status code gives the result at a glance. The response body can provide more detail.

Why do we need status codes?

Status codes help the browser, mobile app, or another API decide what to do next. A client can display validation errors for 400, ask the user to sign in for 401, stop or delay requests after 429, and handle a temporary server failure after 503.

They also make your API predictable. If every response says 200 OK, a client cannot reliably tell success from failure.

Five groups 

A 4xx response does not always mean a programming bug in the client. For example, 409 Conflict can result from two valid users updating the same record. Likewise, a 5xx response can originate from a dependency such as another API.

1xx — Informational

These are interim responses. You rarely return them directly from an ASP.NET Core controller.

Key point: 102 Processing does not mean “your background job has been queued.” For an API that has accepted work but will complete it later, 202 Accepted is usually the relevant code. (MDN)

2xx — Success

Important differences

• 200 vs 204: Both mean success. Choose 200 when returning data; choose 204 when there is no response body.

• 201 vs 202: 201 means the resource has been created. 202 means the work has been accepted and may finish later.

• For 201, CreatedAtAction(...) is useful because it returns the created resource and a Location header pointing to it. (Microsoft Learn)

[HttpPost]
public IActionResult Create(Product product)
{
    product.Id = 10; // Example: normally assigned when saved

    return CreatedAtAction(
        nameof(GetById),
        new { id = product.Id },
        product);
}

3xx — Redirection and caching

Pay attention to 302 versus 307, and 301 versus 308 when redirecting a POST. 307 and 308 explicitly preserve the request method. Also, 304 is about caching: it tells the client to use its existing representation; it does not return the resource body again. (rfc-editor.org)

4xx — The request cannot be completed as sent

This is the largest section. The following are the most useful distinctions for ASP.NET Core interviews and day-to-day API development.

Four distinctions worth remembering

401 vs 403

• 401: “Who are you? Supply valid authentication.”

• 403: “I know who you are, but you cannot do this.”

Despite its name, 401 Unauthorized refers to authentication. (rfc-editor.org)

400 vs 422

Suppose your API receives an order:

{ "quantity": -5 }

A typical ASP.NET Core API can return 400 Bad Request for validation failure, especially when using [ApiController] and model validation. Some API designs choose 422 Unprocessable Content when they want to distinguish understood but semantically invalid content. The choice should be consistent across your API; ASP.NET Core does not automatically use 422 for every validation failure. (Microsoft Learn)

409 vs 412

• 409 Conflict: A general conflict with the resource's current state.

• 412 Precondition Failed: A specific condition supplied by the client, commonly If-Match, failed.

406 vs 415

• 406: Problem with the response format requested through Accept.

• 415: Problem with the request body format declared through Content-Type. (rfc-editor.org)

5xx — Server or upstream failure

500 vs 502 vs 503 vs 504

Imagine this flow: Client → API Gateway → Products API.

• 500: Products API encounters an unexpected exception.

• 502: The gateway receives an invalid response from Products API.

• 503: A service is temporarily unable to handle the request.

• 504: The gateway waits for Products API and times out.

These codes describe different failures, which helps you decide where to investigate. (rfc-editor.org)

How to return common codes in an ASP.NET Core controller

[HttpGet("{id}")]
public IActionResult GetById(int id)
{
    var product = FindProduct(id);

    if (product is null)
        return NotFound();                    // 404

    return Ok(product);                       // 200
}

[HttpDelete("{id}")]
public IActionResult Delete(int id)
{
    // Delete the product...
    return NoContent();                       // 204
}

These are examples of controller results; authentication middleware, rate limiting, hosting infrastructure, and gateways can also produce status codes before your action runs. ASP.NET Core documents the controller action results and its automatic 400 behavior with [ApiController]. (Microsoft Learn)

Key points for quick revision

1. 2xx = succeeded; 4xx = request cannot be completed as sent; 5xx = server-side failure.

2. Use 200 for success with data, 201 for a created resource, 202 for accepted work, and 204 for success without a body.

3. Use 401 for missing or invalid authentication; 403 for insufficient permission.

4. Use 404 when the requested resource does not exist; 405 when its HTTP method is unsupported.

5. 406 checks Accept; 415 checks Content-Type.

6. 409 is a conflict; 412 means a supplied precondition failed.

7. 429 means the request rate limit was exceeded.

8. 502 is a bad upstream response; 504 is an upstream timeout; 503 means temporary unavailability.

9. Do not return 200 with an error message for every failure. Give clients a meaningful status code and an appropriate error response.

10. Particularly 102, 205, 418, 501, and 511—need the qualifications above when discussed in an interview.