Isaac.

HTTP Status Codes

Learn how to understand and use HTTP status codes effectively in web applications and APIs.

By EMEPublished: February 20, 2025
httpstatus codesapiweb developmentrest

A Simple Analogy

Imagine ordering a pizza and getting different responses. If everything goes well, the restaurant says "Got it, your order is confirmed" (200 OK). If they're out of pizza, they say "Sorry, we don't have that" (404 Not Found). If they're closed, they say "We're not here right now" (503 Service Unavailable). HTTP status codes are like those responses—they tell you what happened with your request.

What Are HTTP Status Codes?

HTTP status codes are three-digit numbers that servers send back to tell clients (browsers, apps) what happened to their request. They're part of every HTTP response and help both humans and machines understand the outcome.

Why Do Status Codes Matter?

  • Clarity: Know immediately if your request succeeded, failed, or needs more action
  • Debugging: Identify problems faster (client error, server error, redirect, etc.)
  • Automation: Programs can handle responses differently based on status code
  • User experience: Build meaningful error messages and recovery flows

The Five Classes of Status Codes

1xx - Informational (Request received, continuing)

  • 100 Continue: Go ahead and send the request body
  • 101 Switching Protocols: Upgrade to a different protocol (WebSocket, HTTP/2)

2xx - Success (Request succeeded)

  • 200 OK: Everything worked, here's the result
  • 201 Created: Resource was successfully created
  • 202 Accepted: Request accepted but not yet processed (async operations)
  • 204 No Content: Success but no content to return

3xx - Redirection (Further action needed)

  • 301 Moved Permanently: Resource moved to a new URL (old URL is outdated)
  • 302 Found: Temporary redirect
  • 304 Not Modified: Client already has the latest version (no need to retransmit)
  • 307 Temporary Redirect: Like 302 but preserves HTTP method

4xx - Client Error (Request is wrong or invalid)

  • 400 Bad Request: Malformed request syntax
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Authenticated but not allowed to access
  • 404 Not Found: Resource doesn't exist
  • 409 Conflict: Request conflicts with current state (duplicate entry)
  • 422 Unprocessable Entity: Request is well-formed but contains logical errors (validation failed)
  • 429 Too Many Requests: Rate limit exceeded

5xx - Server Error (Server failed)

  • 500 Internal Server Error: Unexpected server error
  • 502 Bad Gateway: Invalid response from upstream server
  • 503 Service Unavailable: Server temporarily down (maintenance, overload)
  • 504 Gateway Timeout: Upstream server didn't respond in time

Practical Examples

Successful Request

GET /api/products/42 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{ "id": 42, "name": "Widget", "price": 19.99 }

Client Error (Missing Resource)

GET /api/products/999 HTTP/1.1

HTTP/1.1 404 Not Found
{ "error": "Product not found" }

Validation Error

POST /api/users HTTP/1.1
{ "email": "invalid-email" }

HTTP/1.1 422 Unprocessable Entity
{ "errors": { "email": "Invalid email format" } }

Redirect

GET /old-page HTTP/1.1

HTTP/1.1 301 Moved Permanently
Location: https://example.com/new-page

Authentication Required

GET /api/admin/dashboard HTTP/1.1

HTTP/1.1 401 Unauthorized
{ "error": "Missing authorization header" }

Real-World Use Cases

  • Web APIs: Return appropriate codes so clients know what to do next
  • SPAs: Handle errors gracefully based on status codes
  • Mobile apps: Retry on 5xx, show user message on 4xx
  • Caching: Use 304 to save bandwidth
  • Rate limiting: Return 429 and let clients backoff

Best Practices

  • Use the correct status code for the situation (don't always use 200)
  • Include meaningful error messages in the response body
  • Document which codes your API returns
  • Use 2xx only for success, 3xx for redirects, 4xx for client errors, 5xx for server errors
  • Handle redirects automatically (most HTTP clients do)
  • Never return 200 with an error message inside—use the right status code instead

Related Concepts to Explore

  • HTTP Methods (GET, POST, PUT, DELETE, PATCH)
  • REST API design principles
  • Error handling and recovery strategies
  • Response headers (Content-Type, Location, Retry-After)
  • Caching with ETags and Cache-Control
  • CORS and HTTP headers
  • Rate limiting and backoff strategies
  • Logging and monitoring HTTP responses
  • GraphQL error handling (different from REST)
  • gRPC and alternative protocols

Summary

HTTP status codes are a simple yet powerful language between clients and servers. By using the right code for each situation, you make your APIs predictable, your apps more reliable, and your debugging faster. Master them, and you've got one of the foundation stones of web development.