REST API Status Codes — Choosing the Right HTTP Status Code for API Responses

Overview

Complete guide to choosing correct HTTP status codes for REST API responses including CRUD operations, validation errors, and authentication failures.

Key Details

• Using correct HTTP status codes makes APIs self-documenting and follows REST conventions
• 200 OK for successful GET/PUT/PATCH, 201 Created for POST, 204 No Content for DELETE
• 400 Bad Request for validation errors, 401 Unauthorized for missing auth, 403 Forbidden for insufficient permissions
• 404 Not Found for missing resources, 409 Conflict for state conflicts, 422 Unprocessable Entity for semantic errors
• 500 Internal Server Error for unexpected server failures — never expose internal details

Common Causes

• Using 200 for all responses and encoding the actual status in the response body
• Confusing 401 (not authenticated) with 403 (authenticated but not authorized)
• Returning 500 for client errors that should be 4xx
• Using 404 for deleted resources instead of 410 Gone

Steps

1. 1Map CRUD to status codes: POST->201, GET->200, PUT->200, PATCH->200, DELETE->204
2. 2Use 400 for malformed requests, 422 for well-formed but semantically invalid requests
3. 3Return 401 when credentials are missing or invalid, 403 when authenticated but unauthorized for the resource
4. 4Use 409 Conflict for duplicate key violations and state transition errors
5. 5Always include a machine-readable error code and human-readable message in error response bodies

Tags

More in 2xx Success

Frequently Asked Questions