HTTP Status Codes: Complete Reference Guide by Category

Updated March 2026 · 8 min read

HTTP status codes are the language your server speaks to clients. Every API response, web page load, and redirect is communicated through these three-digit codes. Understanding them is essential for building robust web applications, debugging API issues, and configuring proper error handling.

Status Code Categories

1xx Informational

2xx Success

REST API Best Practices for 2xx

// POST /api/users → 201 Created (with Location header)
HTTP/1.1 201 Created
Location: /api/users/42
Content-Type: application/json

{"id": 42, "name": "Alice", "email": "[email protected]"}

// DELETE /api/users/42 → 204 No Content
HTTP/1.1 204 No Content

// PUT /api/users/42 → 200 OK (with updated resource)
HTTP/1.1 200 OK
Content-Type: application/json

{"id": 42, "name": "Alice Updated"}

3xx Redirection

SEO Impact of Redirects

• 301 passes ~90-99% of link equity (SEO value) to the new URL. Use for permanent URL changes.
• 302 does not pass link equity (search engines keep indexing the original URL).
• Redirect chains (A→B→C) lose SEO value at each hop. Keep them under 2 hops.
• Check redirect behavior with the HTTP Header Checker.

4xx Client Errors

401 vs 403: The Key Difference

// 401 Unauthorized - "Who are you?"
// The client has not provided authentication credentials.
// Fix: Include a valid Bearer token or API key.
GET /api/admin
Authorization: (missing)
→ 401 Unauthorized

// 403 Forbidden - "I know who you are, but you can't do this."
// The client is authenticated but lacks permission.
GET /api/admin
Authorization: Bearer valid-user-token
→ 403 Forbidden (user is not an admin)

5xx Server Errors

Debugging 502 and 504 Errors

# Common causes of 502 Bad Gateway:
# 1. Backend application crashed or is not running
# 2. Wrong upstream address in reverse proxy config
# 3. Backend returned malformed response

# Check if the backend is running
curl http://localhost:8000/api/v1/health

# Check Nginx/Caddy error logs
tail -f /var/log/nginx/error.log

# Common causes of 504 Gateway Timeout:
# 1. Backend is too slow (database query, external API)
# 2. Proxy timeout too short
# Increase proxy timeout:
# nginx: proxy_read_timeout 120s;
# caddy: transport http { read_timeout 120s }

Status Codes in API Design

// Well-designed REST API responses:

// List resources
GET /api/tools → 200 OK

// Create resource
POST /api/tools → 201 Created

// Update resource
PUT /api/tools/1 → 200 OK (or 204 No Content)

// Delete resource
DELETE /api/tools/1 → 204 No Content

// Validation error
POST /api/tools (invalid data) → 422 Unprocessable Entity
{
  "errors": [
    {"field": "name", "message": "Name is required"},
    {"field": "url", "message": "Invalid URL format"}
  ]
}

// Rate limited
GET /api/tools → 429 Too Many Requests
Retry-After: 60

FAQ

Should I use 200 or 204 for successful updates?

Use 200 if you return the updated resource in the response body. Use 204 if there is no response body. The choice depends on whether clients need the updated data back immediately.

What is the difference between 302 and 307?

302 may change the HTTP method to GET on redirect (browsers do this). 307 guarantees the method is preserved. If you are redirecting a POST request and want it to remain a POST, use 307.

When should I return 400 vs 422?

400 means the request is syntactically malformed (unparseable JSON, missing Content-Type). 422 means the syntax is valid but the data fails business validation (invalid email format, negative quantity). Many APIs use 400 for both, but 422 is more precise.

What status code should a health check return?

Return 200 when the service is healthy and 503 when it is not ready to accept traffic (e.g., database connection lost, warming up).

DevToolKit — 42+ Free Online Developer Tools