Proper HTTP Status Codes: Common Mistakes

APIs return incorrect HTTP status codes (e.g., 200 for errors, 500 for validation failures, 404 for auth failures), confusing clients and breaking standard HTTP semantics.

Use semantically correct HTTP status codes for each scenario.

// Authentication/Authorization
401 Unauthorized — no credentials or invalid token (misleadingly named)
403 Forbidden — valid credentials but insufficient permissions

// Client errors
400 Bad Request — malformed request syntax or invalid parameters
404 Not Found — resource doesn't exist
409 Conflict — resource state conflict (duplicate, version mismatch)
410 Gone — resource permanently deleted
422 Unprocessable Entity — valid syntax but semantic validation failure
429 Too Many Requests — rate limit exceeded

// Success
200 OK — general success with body
201 Created — resource created (include Location header)
204 No Content — success with no body (DELETE)
206 Partial Content — pagination/range response

// Server errors
500 Internal Server Error — unexpected server fault
502 Bad Gateway — upstream service failed
503 Service Unavailable — intentional (maintenance, overload)

HTTP status codes are the primary error communication channel for APIs. Incorrect codes break client error handling, caching, and retry logic.