HTTP Status Codes

Definition

HTTP status codes are three-digit numbers that tell you the result of an HTTP request. Every HTTP response includes a status code - it’s the server’s way of saying “here’s what happened with your request.”

Status codes are grouped into five classes by their first digit: 1xx (informational), 2xx (success), 3xx (redirection), 4xx (client error), and 5xx (server error). The most famous is probably 404 Not Found, but there are dozens more, each with specific meaning.

Understanding status codes is crucial for building and debugging APIs. They let clients know if they need to retry (5xx), if they made a mistake (4xx), if they should redirect (3xx), or if everything worked perfectly (2xx).

Example

2xx Success: 200 OK (GET succeeded), 201 Created (POST succeeded), 204 No Content (DELETE succeeded)

4xx Client Errors: 400 Bad Request (invalid JSON), 401 Unauthorized (missing auth), 403 Forbidden (lacks permission), 404 Not Found (resource doesn’t exist), 429 Too Many Requests (rate limited)

5xx Server Errors: 500 Internal Server Error (server crashed), 502 Bad Gateway (upstream server failed), 503 Service Unavailable (server overloaded)

3xx Redirects: 301 Moved Permanently (resource relocated), 304 Not Modified (cached version is current)

Diagram

graph TD
A[HTTP Status Codes] --> B[1xx Informational]
A --> C[2xx Success]
A --> D[3xx Redirection]
A --> E[4xx Client Error]
A --> F[5xx Server Error]
C --> C1[200 OK]
C --> C2[201 Created]
C --> C3[204 No Content]
E --> E1[400 Bad Request]
E --> E2[401 Unauthorized]
E --> E3[403 Forbidden]
E --> E4[404 Not Found]
E --> E5[429 Too Many Requests]
F --> F1[500 Internal Server Error]
F --> F2[502 Bad Gateway]
F --> F3[503 Service Unavailable]

Best Practices

1. Use the most specific status code available
2. Return 2xx for successful operations
3. Use 4xx for client mistakes (bad input, missing auth)
4. Use 5xx only for actual server failures
5. Return 201 Created (not 200 OK) for POST creation
6. Return 204 No Content for DELETE success
7. Include error details in response body for 4xx/5xx
8. Use 429 with Retry-After header for rate limiting
9. Avoid returning 200 for failed operations
10. Document which status codes each endpoint returns

Common Mistakes

Returning 200 OK for everything (even errors), using 500 when it’s a client error (use 400), returning 404 when resource exists but user lacks permission (use 403), not including error details in response body, inconsistent error format across endpoints, returning 201 without Location header.

Standards & RFCs

Related Terms