Understanding HTTP Status Codes in REST APIs

HTTP status codes are standardized response codes returned by a web server to indicate the outcome of an HTTP request. In RESTful APIs, these codes play a crucial role in communicating the result of API operations to clients in a consistent and predictable manner.

Choosing the appropriate status code is essential for several reasons:

1. Clear communication: Status codes provide immediate feedback about what happened with the request
2. Protocol compliance: Using standard HTTP status codes ensures compatibility with HTTP infrastructure
3. Client error handling: Consistent status codes enable clients to implement reliable error handling
4. Debugging: Accurate status codes simplify troubleshooting and problem diagnosis
5. Caching behavior: Certain status codes influence how responses are cached

For example, a server can process a request synchronously and respond with 200 OK, but it can also accept a request for asynchronous processing and respond with 202 Accepted. Similarly, a newly created resource should return 201 Created rather than a generic 200 OK to accurately reflect what happened.

Status Code Categories

The first digit of the status code defines the class of response. HTTP status codes are grouped into five categories:

Commonly Used Status Codes in REST APIs

Below are the most commonly used HTTP status codes in REST APIs, organized by category, with guidelines on when to use each one.

2xx - Success

3xx - Redirection

4xx - Client Error

5xx - Server Error

Implementation Best Practices

1. Be Specific with Status Codes

Use the most specific status code that applies to the situation. For example, use 404 Not Found for missing resources rather than a generic 400 Bad Request.

2. Consistent Error Responses

Return consistent JSON error bodies with your status codes:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "The product name must be between 3 and 50 characters",
  "type": "https://example.com/errors/validation",
  "instance": "/products/create",
  "errors": {
    "name": ["The field Name must be between 3 and 50 characters."]
  }
}

ASP.NET Core Implementation:

public class ErrorResponse
{
    public int Status { get; set; }
    public string Title { get; set; }
    public string Detail { get; set; }
    public string Type { get; set; }
    public string Instance { get; set; }
    public Dictionary<string, string[]> Errors { get; set; }
}

// In a controller action
[HttpPost]
public IActionResult CreateProduct(ProductModel model)
{
    if (!ModelState.IsValid)
    {
        var errorResponse = new ErrorResponse
        {
            Status = 400,
            Title = "Bad Request",
            Detail = "Validation failed",
            Instance = HttpContext.Request.Path,
            Errors = ModelState.ToDictionary(
                kvp => kvp.Key,
                kvp => kvp.Value.Errors.Select(e => e.ErrorMessage).ToArray()
            )
        };
        
        return BadRequest(errorResponse);
    }
    
    // Create product logic...
}

3. HTTP Method and Status Code Relationships

Different HTTP methods have appropriate status codes for successful operations:

4. Handling Asynchronous Operations

For long-running processes, use a pattern like:

1. Return 202 Accepted with a resource URL for checking status
2. Provide a status endpoint that returns 200 OK with progress information
3. When complete, return either 303 See Other with the resource location or the completed resource with 200 OK

[HttpPost("long-running")]
public IActionResult StartLongRunningOperation(OperationRequest request)
{
    string operationId = _operationService.StartOperation(request);
    
    // Return 202 Accepted with a URL to check the status
    Response.Headers.Add("Location", $"/api/operations/{operationId}");
    return Accepted(new { id = operationId, status = "Processing" });
}

[HttpGet("operations/{id}")]
public IActionResult GetOperationStatus(string id)
{
    OperationStatus status = _operationService.GetStatus(id);
    
    if (status.IsComplete)
    {
        // Option 1: Redirect to the created resource
        return RedirectToAction("GetResource", new { id = status.ResourceId });
        
        // Option 2: Return the status with completion info
        // return Ok(new { id = status.ResourceId, status = "Complete" });
    }
    
    return Ok(new { 
        id = id, 
        status = "Processing", 
        percentComplete = status.PercentComplete 
    });
}

5. Pagination Headers

Include pagination information in HTTP headers:

[HttpGet]
public IActionResult GetItems([FromQuery] PaginationParameters parameters)
{
    var (items, totalCount, pageCount) = _itemService.GetPaginatedItems(parameters);
    
    Response.Headers.Add("X-Total-Count", totalCount.ToString());
    Response.Headers.Add("X-Page-Count", pageCount.ToString());
    
    // Create links for HATEOAS
    var links = new List<LinkDto>();
    
    // Add first, prev, next, last links as appropriate
    
    Response.Headers.Add("Link", string.Join(", ", links));
    
    return Ok(items);
}

Common Anti-Patterns to Avoid

1. Using 200 OK for everything: Each response should use the most appropriate status code.

2. Returning 404 Not Found for authorization failures: Use 401 Unauthorized for authentication issues and 403 Forbidden for permission issues.

3. Returning 500 Internal Server Error for validation failures: Use 400 Bad Request or 422 Unprocessable Entity for validation issues.

4. Using non-standard status codes: Stick to widely recognized HTTP status codes.

5. Not including adequate error details: Status codes alone are often insufficient; include useful error messages.

Status Code Selection Flow Chart

Request Received
├─► Authentication Problem? → 401 Unauthorized
│   ↓
├─► Authorization Problem? → 403 Forbidden
│   ↓
├─► Resource Not Found? → 404 Not Found
│   ↓
├─► Validation Failed? → 400 Bad Request or 422 Unprocessable Entity
│   ↓
├─► Request Rate Exceeded? → 429 Too Many Requests
│   ↓
├─► Resource Conflict? → 409 Conflict
│   ↓
├─► Success with No Content? → 204 No Content
│   ↓
├─► Resource Created? → 201 Created
│   ↓
├─► Asynchronous Operation? → 202 Accepted
│   ↓
└─► Success with Content → 200 OK

Resources

• IETF RFC 7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
• HTTP Status Codes Specification
• Microsoft REST API Guidelines - Microsoft’s recommendations for REST API design