Lesson 2 Understanding HTTP Status Codes –
Returning Proper API Responses in [Link]
Core
These notes are prepared based on the tutorial: Understanding HTTP Status Codes – Returning Proper API
Responses in [Link] Core by CodeWithMukesh.
1. Why HTTP Status Codes Matter
HTTP status codes are a contract between APIs and clients. Clients, browsers, mobile apps, and monitoring tools
depend on proper status codes to understand what happened during a request.
Never return 200 OK for errors.
2. HTTP Status Code Categories
1xx → Informational
2xx → Success
3xx → Redirection
4xx → Client Errors
5xx → Server Errors
3. 200 OK
Used when the request succeeds and data is returned.
Examples:
- GET endpoints
- Query/search results
- Successful operations
4. 201 Created
Used when a new resource is successfully created.
Best practices:
- Include Location header
- Return created resource
- Mostly used with POST requests
5. 204 No Content
Used when the request succeeds but nothing needs to be returned.
Typical usage:
- DELETE operations
- PUT/PATCH operations without response body
6. 202 Accepted
Used when the request is accepted but processing is asynchronous and not yet complete.
Useful for background jobs and queue processing.
7. 400 Bad Request
Used when the request is malformed or invalid.
Examples:
- Invalid JSON
- Missing fields
- Wrong data types
8. 401 Unauthorized
Means the user is not authenticated.
Examples:
- Missing JWT token
- Expired token
- Invalid credentials
9. 403 Forbidden
Means the user is authenticated but does not have permission to access the resource.
10. 404 Not Found
Returned when the requested resource does not exist.
Example:
- User ID not found
- Product does not exist
11. 409 Conflict
Used when the request conflicts with the current state of the resource.
Examples:
- Duplicate email address
- Concurrency conflicts
12. 422 Unprocessable Entity
Used when the request syntax is valid but validation rules fail.
Example:
- Price must be greater than zero
- Name is required
13. 429 Too Many Requests
Used for rate limiting when the client sends too many requests in a short period.
14. 500 Internal Server Error
Used for unexpected server-side failures.
Do NOT use 500 for client-side validation errors.
15. Returning Status Codes in Minimal APIs
[Link] Core Minimal APIs use the Results class.
Examples:
[Link]()
[Link]()
[Link]()
[Link]()
[Link]()
16. Returning Status Codes in Controllers
Controllers use IActionResult helper methods.
Examples:
Ok()
CreatedAtAction()
NotFound()
BadRequest()
Conflict()
17. TypedResults in .NET
TypedResults provide:
- Better OpenAPI documentation
- Compile-time safety
- Strongly typed responses
18. Common Mistakes
1. Returning 200 for errors
2. Confusing 401 and 403
3. Using 500 for validation errors
4. Ignoring proper status codes
5. Returning 200 instead of 201 for resource creation
19. Quick Reference Table
200 → Success with data
201 → Resource created
204 → Success without body
400 → Bad request
401 → Unauthorized
403 → Forbidden
404 → Not found
409 → Conflict
422 → Validation failure
429 → Too many requests
500 → Internal server error
20. Key Takeaways
Use proper HTTP status codes consistently.
Clients and monitoring systems depend on them.
Correct status codes make APIs professional, predictable, and easier to integrate.
21. Example Minimal API Code
[Link]("/products", async (CreateProductRequest request, AppDbContext db) =>
{
var product = new Product
{
Name = [Link],
Price = [Link]
};
[Link](product);
await [Link]();
return [Link]($"/products/{[Link]}", product);
});
Main Learning Outcome:
Professional APIs must return accurate HTTP status codes. Correct status codes improve client integration,
debugging, monitoring, and API usability.