HTTP Status Codes Explained: A Backend Developer’s Survival Guide

The Essential Guide to HTTP Status Codes for Backend Developers

Mastering server responses for robust APIs and web applications

📖 Table of Contents

1. Introduction
   1.1 What Are HTTP Status Codes?
   1.2 Why Status Codes Matter for Backend Devs
2. Informational (1xx)
   2.1 100 Continue
3. Success (2xx)
   3.1 200 OK
   3.2 201 Created
   3.3 204 No Content
4. Redirection (3xx)
   4.1 301 Moved Permanently
   4.2 308 Permanent Redirect
5. Client Errors (4xx)
   5.1 400 Bad Request
   5.2 401 Unauthorized
   5.3 403 Forbidden
   5.4 404 Not Found
   5.5 429 Too Many Requests
6. Server Errors (5xx)
   6.1 500 Internal Server Error
   6.2 502 Bad Gateway
   6.3 503 Service Unavailable
   6.4 504 Gateway Timeout
7. Best Practices
   7.1 Semantic Status Codes
   7.2 Structured Error Responses
8. Real-World Example
   8.1 User Login Flow

1. Introduction

HTTP status codes are 3-digit numbers returned by servers to indicate request outcomes. For backend developers, they’re critical for debugging, API design, and user experience.

1.1 What Are HTTP Status Codes?

Standardized responses from servers to clients (e.g., browsers, APIs) that describe the result of a request.

1.2 Why Status Codes Matter for Backend Devs

• Debugging: Quickly identify client/server issues.
• API Contracts: Clear expectations for frontend/mobile teams.
• Security: Proper auth (401 vs 403) prevents vulnerabilities.

2. Informational (1xx)

Temporary responses during request processing.

2.1 100 Continue

• Description: Server acknowledges request headers; client should send the body.
• Use Case: Large file uploads (e.g., confirm server readiness before sending 1GB video).
• Example:

  HTTP/1.1 100 Continue  
  [Client sends file data]
  

3. Success (2xx)

Requests successfully processed.

3.1 200 OK

• Description: Standard success response (GET/PUT/PATCH).
• Example:

  { "id": 101, "name": "Alice" }
  

3.2 201 Created

• Description: Resource created (e.g., after POST).
• Headers: Include Location: /users/101.

3.3 204 No Content

• Description: Success with no response body (e.g., DELETE).

Mermaid: Typical 2xx Flow

4. Redirection (3xx)

Client must take additional action.

4.1 301 Moved Permanently

• Description: Resource moved to new URL (SEO-friendly).
• Headers: Location: /new-path.

4.2 308 Permanent Redirect

• Description: Same as 301, but preserves HTTP method (PUT→PUT).

5. Client Errors (4xx)

Client-side mistakes.

5.1 400 Bad Request

• Description: Malformed syntax (e.g., invalid JSON).
• Fix:

  if not request.json.get("email"):
      return {"error": "Email required"}, 400
  

5.2 401 Unauthorized

• Description: Missing/invalid authentication.
• Headers: WWW-Authenticate: Bearer.

5.3 403 Forbidden

• Description: Authenticated but insufficient permissions.

5.4 404 Not Found

• Description: Resource doesn’t exist.
• Example:

  { "error": "User ID 999 not found" }
  

5.5 429 Too Many Requests

• Description: Rate limit exceeded.
• Headers: Retry-After: 60.

Mermaid: 4xx Error Handling

6. Server Errors (5xx)

Server-side failures.

6.1 500 Internal Server Error

• Description: Unhandled exception (log details!).

6.2 502 Bad Gateway

• Description: Upstream server (e.g., auth microservice) failed.

6.3 503 Service Unavailable

• Description: Server overloaded/maintenance.

6.4 504 Gateway Timeout

• Description: Upstream server timeout.

Mermaid: 5xx in Microservices

7. Best Practices

7.1 Semantic Status Codes

• Use 401 for auth failures, 403 for permission issues.
• Avoid 200 for errors.

7.2 Structured Error Responses

{
  "code": "VALIDATION_ERROR",
  "details": ["Email must be valid"]
}

8. Real-World Example

8.1 User Login Flow

POST /login
# Success → 200 OK
{ "token": "abcd1234" }

# Failure → 401
{ "code": "INVALID_CREDENTIALS" }