Complete HTTP Status Codes for .NET Core APIs

1xx – Informational

Code	Name	When to Use
100	Continue	Client should continue with request (rare in APIs)
101	Switching Protocols	Upgrading to WebSocket
102	Processing	Long-running operation in progress (WebDAV)
103	Early Hints	Send headers before final response

2xx – Success

Code	Name	When to Use
200	OK	Standard success – GET, PUT, PATCH
201	Created	POST created new resource – include Location header
202	Accepted	Request accepted, processing async (queued jobs)
204	No Content	DELETE success, or PUT/PATCH with no response body
205	Reset Content	Tell client to reset form/view
206	Partial Content	Returning part of resource (Range requests)
207	Multi-Status	Multiple operation results (WebDAV)
208	Already Reported	Resource already reported (WebDAV)
226	IM Used	Delta encoding applied

3xx – Redirection

Code	Name	When to Use
300	Multiple Choices	Multiple representations available
301	Moved Permanently	Resource moved forever – update bookmarks
302	Found	Temporary redirect – use original URI next time
303	See Other	Redirect to GET after POST
304	Not Modified	Cached version is still valid (ETag match)
307	Temporary Redirect	Like 302 but preserve HTTP method
308	Permanent Redirect	Like 301 but preserve HTTP method

4xx – Client Errors

Code	Name	When to Use
400	Bad Request	Invalid JSON, malformed request, validation failed
401	Unauthorized	Missing or invalid authentication token
402	Payment Required	Payment needed (rarely used)
403	Forbidden	Authenticated but not authorized (no permission)
404	Not Found	Resource doesn’t exist
405	Method Not Allowed	Wrong HTTP verb (POST to GET-only endpoint)
406	Not Acceptable	Can’t produce requested Accept format
407	Proxy Authentication Required	Proxy needs authentication
408	Request Timeout	Client took too long to send request
409	Conflict	Resource conflict (duplicate, version mismatch)
410	Gone	Resource permanently deleted
411	Length Required	Content-Length header missing
412	Precondition Failed	If-Match or If-None-Match failed
413	Payload Too Large	Request body exceeds limit
414	URI Too Long	URL exceeds maximum length
415	Unsupported Media Type	Wrong Content-Type (sent XML, expected JSON)
416	Range Not Satisfiable	Invalid Range header
417	Expectation Failed	Expect header can’t be met
418	I’m a Teapot	Easter egg (don’t use in production)
421	Misdirected Request	Request sent to wrong server
422	Unprocessable Entity	Valid JSON but business logic validation failed
423	Locked	Resource is locked (WebDAV)
424	Failed Dependency	Request failed due to previous failure
425	Too Early	Server unwilling to risk replay attack
426	Upgrade Required	Client must upgrade protocol
428	Precondition Required	Request must be conditional
429	Too Many Requests	Rate limit exceeded
431	Request Header Fields Too Large	Headers too large
451	Unavailable For Legal Reasons	Censored/blocked by law

5xx – Server Errors

Code	Name	When to Use
500	Internal Server Error	Unhandled exception, generic server error
501	Not Implemented	Feature not implemented
502	Bad Gateway	Invalid response from upstream server
503	Service Unavailable	Server overloaded or maintenance mode
504	Gateway Timeout	Upstream server timeout
505	HTTP Version Not Supported	HTTP version not supported
506	Variant Also Negotiates	Content negotiation error
507	Insufficient Storage	Server out of storage (WebDAV)
508	Loop Detected	Infinite loop in request (WebDAV)
510	Not Extended	Further extensions needed
511	Network Authentication Required	Network access requires authentication

---

.NET Core Implementation Examples

// Most common patterns in .NET Core APIs

// Success responses
return Ok(data);                          // 200
return Created($"/api/users/{id}", user); // 201
return NoContent();                       // 204

// Client errors
return BadRequest("Invalid input");       // 400
return Unauthorized();                    // 401
return Forbid();                          // 403
return NotFound();                        // 404
return Conflict("User already exists");   // 409
return UnprocessableEntity(errors);       // 422
return StatusCode(429, "Rate limited");   // 429

// Server errors
return StatusCode(500, "Internal error"); // 500
return StatusCode(503, "Unavailable");    // 503

Quick Decision Guide

Creating resource? → 201 Created
Deleting resource? → 204 No Content
Updating resource? → 200 OK or 204 No Content
Invalid JSON/format? → 400 Bad Request
Business validation failed? → 422 Unprocessable Entity
No auth token? → 401 Unauthorized
Valid token, no permission? → 403 Forbidden
Resource doesn’t exist? → 404 Not Found
Duplicate resource? → 409 Conflict
Unhandled exception? → 500 Internal Server Error
External API failed? → 502 Bad Gateway
Too many requests? → 429 Too Many Requests

Common Mistakes

❌ 401 vs 403: Use 401 for missing/invalid credentials, 403 for insufficient permissions
❌ 400 vs 422: Use 400 for malformed requests, 422 for valid format but invalid business logic
❌ 200 vs 204: Use 204 when there’s no response body (especially DELETE)
❌ 404 vs 410: Use 410 only if resource was intentionally removed and won’t return
❌ 502 vs 504: Use 502 for bad response from upstream, 504 for timeout