HTTP Status Codes: The Complete Guide for Developers

HTTP status codes are the backbone of web communication. Understanding them helps you debug issues, build better APIs, and improve user experience. Here's everything you need to know.

The Five Classes

HTTP responses are grouped into five classes:

• 1xx — Informational: Request received, continuing
• 2xx — Success: Request successfully received and understood
• 3xx — Redirection: Further action needed
• 4xx — Client Error: Problem with the request
• 5xx — Server Error: Server failed to fulfill request

2xx — Success Codes

200 OK

The most common code. Request succeeded. Response body contains the result.

GET /api/users/123 → 200 OK
{ "id": 123, "name": "Alice" }

201 Created

Resource was successfully created. Use for POST requests that create new records.

POST /api/users → 201 Created
Location: /api/users/456

204 No Content

Success but no response body. Use for DELETE requests or successful updates where you don't return data.

DELETE /api/users/123 → 204 No Content

3xx — Redirection Codes

301 Moved Permanently

Resource has a new permanent URL. Browsers and search engines cache this. Use for SEO when changing URLs.

SEO Impact: 301 passes 90-99% of "link juice" to the new URL. Always use 301 for permanent moves.

302 Found (Temporary Redirect)

Temporary redirect. The original URL will be used again in the future. Search engines keep the old URL indexed.

304 Not Modified

Response hasn't changed since last request. Used for caching — client uses its cached version.

# Client sends:
If-Modified-Since: Mon, 01 Jan 2024 00:00:00 GMT
# Server checks, finds unchanged:
GET /api/data → 304 Not Modified

307 Temporary Redirect

Like 302 but guarantees the request method won't change. Use when POST data must be preserved.

4xx — Client Error Codes

400 Bad Request

Server can't process the request due to malformed syntax or invalid data. Include error details in response.

POST /api/users → 400 Bad Request
{
  "error": "validation_error",
  "message": "Email format is invalid"
}

401 Unauthorized

Authentication is required or has failed. The client must provide valid credentials.

Common Mistake: 401 means "you need to log in." 403 means "you're logged in but don't have permission."

403 Forbidden

Client is authenticated but doesn't have permission. The server understands the request but refuses to fulfill it.

404 Not Found

The resource doesn't exist. For APIs, distinguish between "doesn't exist" (404) and "endpoint not found" (501).

GET /api/users/999 → 404 Not Found
{
  "error": "not_found",
  "message": "User with ID 999 not found"
}

405 Method Not Allowed

HTTP method is not supported for this endpoint. Include Allow header with supported methods.

DELETE /api/posts → 405 Method Not Allowed
Allow: GET, POST

409 Conflict

Request conflicts with current state. Use when trying to create a resource that already exists, or conflicting updates.

POST /api/users → 409 Conflict
{
  "error": "conflict",
  "message": "Username 'alice' already taken"
}

422 Unprocessable Entity

Request format is correct but content is semantically invalid. Use for validation errors that require business logic checks.

429 Too Many Requests

Rate limit exceeded. Include Retry-After header with seconds until next request is allowed.

GET /api/data → 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0

5xx — Server Error Codes

500 Internal Server Error

Something went wrong on the server side. The generic "catch-all" error. Always log the actual error for debugging.

Never expose stack traces to users in production. Log them server-side, return a generic 500 with a correlation ID.

502 Bad Gateway

Gateway or proxy received an invalid response from upstream server. Common in microservices or CDN configurations.

503 Service Unavailable

Server is temporarily down (maintenance, overload). Include Retry-After header and consider returning a friendly maintenance page.

504 Gateway Timeout

Gateway timed out waiting for upstream server. Similar to 502 but specifically a timeout issue.

Best Practices for API Design

• Return appropriate codes — don't return 200 for errors
• Include error details in response body (not just the code)
• Use consistent error response format
• Include correlation IDs for debugging 5xx errors
• Document all possible response codes for each endpoint

Less Common But Important Codes

100 Continue

Server has received request headers, client should proceed with request body. Useful for large uploads where server may reject the request.

# Client sends headers first
HEAD /api/upload HTTP/1.1
Content-Length: 10485760
Expect: 100-continue

# Server responds:
HTTP/1.1 100 Continue
# Client then sends the body

206 Partial Content

Server returns only part of the resource. Essential for resumable downloads and video streaming.

GET /video/large-file.mp4
Range: bytes=0-1023

HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1023/10485760
Content-Length: 1024

418 I'm a Teapot

April Fools' joke from RFC 2324. Some APIs use it as an easter egg, but it should not be used in production.

451 Unavailable For Legal Reasons

Censorship-related status code. The name is a reference to Fahrenheit 451 (book burning).

Error Response Format

Standardize your error responses across the API:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request could not be processed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "value": "not-an-email"
      },
      {
        "field": "password",
        "message": "Must be at least 8 characters",
        "value": "short"
      }
    ],
    "request_id": "req_abc123xyz"
  }
}

Testing Status Codes

Common tools for testing HTTP responses:

• curl — Command line testing
• Postman — GUI for API testing
• Browser DevTools — Network tab
• httpstat — Visualize response time breakdown

# Test status codes with curl
curl -i https://api.example.com/users
curl -X POST -d '{"name":"test"}' -H "Content-Type: application/json" https://api.example.com/users
curl -I https://api.example.com/users  # HEAD request only

SEO Considerations