HTTP Status Codes

Why status codes matter

The status code is the first thing a client reads. It answers one question before anything else: did this work?

HTTP/1.1 404 Not Found

A client can act on that immediately, without parsing a body or reading English text. That is the point. Returning 200 OK with a body that says { "error": "not found" } forces every client to read your prose. Returning 404 lets any client, in any language, understand instantly.

The five families

The first digit tells you the category. Learn these five and you can guess the rest.

The 4xx versus 5xx split is the one that matters most. 4xx means fix your request. 5xx means the server is broken. If your API returns 500 because a user typed a bad email address, you will spend nights chasing alerts that are not really bugs.

The success codes

200 OK is the everyday success. Use it for GET and for updates where you return the updated object.

return Ok(book);

201 Created means a new resource exists. Always include a Location header pointing at it.

return CreatedAtAction(nameof(GetById), new { id = book.Id }, book);
// or in minimal APIs:
return Results.Created($"/api/books/{book.Id}", book);

204 No Content means it worked and there is nothing to send back. This is the normal answer to DELETE, and a common answer to PUT and PATCH.

return NoContent();

202 Accepted means you took the request but have not finished it yet. Use it when work goes onto a queue.

return Accepted($"/api/jobs/{jobId}");

The client error codes

400 Bad Request means the request itself is wrong. Missing required field, wrong type, malformed JSON.

return BadRequest(new { error = "Year must be greater than 1000." });

With [ApiController] on your controller, model validation failures return 400 automatically. You rarely write this one by hand.

401 Unauthorized means “I do not know who you are”. The name is misleading. It really means unauthenticated. You get this when the token is missing, expired or invalid.

return Unauthorized();

403 Forbidden means “I know who you are, and you are not allowed”. The token is valid, the permission is not there.

return Forbid();

The difference in one line: 401 means log in, 403 means logging in again will not help.

404 Not Found means the resource does not exist.

return NotFound();

409 Conflict means the request clashes with the current state. A duplicate email on signup, or editing a record someone else already changed.

return Conflict(new { error = "That email is already registered." });

422 Unprocessable Entity means the JSON parsed fine and the types are right, but the values break a business rule. Some teams use 400 for everything and never touch 422. Either is acceptable. Be consistent.

429 Too Many Requests means the caller is going too fast. Rate limiting returns this, along with a Retry-After header.

The server error codes

500 Internal Server Error is the catch all. An unhandled exception reached the top of your pipeline. The client can do nothing but retry later.

You should almost never write return StatusCode(500) by hand. Let your global exception handler produce it, so every failure is logged the same way.

503 Service Unavailable means the server is up but cannot serve right now, usually because a dependency is down or you are in maintenance.

A cheat sheet by scenario

An empty list is not a 404

This catches everyone once. GET /api/books?year=1850 finds no books. What do you return?

Return 200 with an empty array. The collection resource /api/books exists. It happens to contain nothing matching your filter. That is a successful query with zero results.

[HttpGet]
public IActionResult Search(int? year)
{
    var results = books.Where(b => year is null || b.Year == year).ToList();
    return Ok(results);      // 200 with [] is correct
}

Return 404 only when the thing you addressed does not exist, such as GET /api/books/9999.

Returning codes in ASP.NET Core

Inside a controller, ControllerBase gives you helper methods:

Ok(value)                  // 200
Created(uri, value)        // 201
CreatedAtAction(...)       // 201 with a generated Location
NoContent()                // 204
BadRequest(value)          // 400
Unauthorized()             // 401
Forbid()                   // 403
NotFound()                 // 404
Conflict(value)            // 409
StatusCode(418)            // anything else

In minimal APIs the same helpers live on the static Results class:

Results.Ok(value);
Results.Created(uri, value);
Results.NoContent();
Results.BadRequest(value);
Results.NotFound();
Results.Problem(statusCode: 503, title: "Database unavailable");

Tell Swagger what you return

Adding [ProducesResponseType] documents the codes an endpoint can return, so Swagger and generated clients know about them:

[HttpGet("{id}")]
[ProducesResponseType(typeof(Book), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public IActionResult GetById(int id) { /* ... */ }

Use the StatusCodes constants rather than raw numbers. StatusCodes.Status404NotFound reads better than 404 and cannot be mistyped.

Quick recap

• The first digit is the family. 2xx worked, 4xx is the caller’s fault, 5xx is yours.
• Never return 500 for bad user input. That turns real alerts into noise.
• 200 for reads, 201 plus a Location header for creates, 204 for deletes and silent updates.
• 401 means not logged in. 403 means logged in but not allowed.
• 409 is for duplicates and state clashes. 429 is for rate limits.
• A search with no matches is 200 with an empty array, not 404.
• Use Ok, NotFound and friends in controllers, and Results.* in minimal APIs.