Understanding HTTP Status Codes: A Complete Reference

HTTP status codes are three-digit numbers returned by web servers to indicate the result of a client's request. Understanding them is crucial for building and debugging web applications.

Status Code Categories

1xx - Informational

The server received the request and is continuing to process it.

• 100 Continue: Server received headers, client should send body
• 101 Switching Protocols: Server is switching to the protocol requested (e.g., WebSocket)
• 103 Early Hints: Used with Link header for preloading resources

2xx - Success

The request was successfully received, understood, and accepted.

• 200 OK: Standard success response
• 201 Created: New resource was successfully created (POST/PUT)
• 204 No Content: Success but no content to return (DELETE)
• 206 Partial Content: Partial resource returned (Range requests)

3xx - Redirection

The client must take additional action to complete the request.

• 301 Moved Permanently: Resource has permanently moved (SEO-friendly)
• 302 Found: Temporary redirect (commonly used but often misused)
• 304 Not Modified: Cached version is still valid
• 307 Temporary Redirect: Like 302 but preserves HTTP method
• 308 Permanent Redirect: Like 301 but preserves HTTP method

4xx - Client Error

The request contains an error from the client side.

• 400 Bad Request: Malformed request syntax
• 401 Unauthorized: Authentication required
• 403 Forbidden: Authenticated but not authorized
• 404 Not Found: Resource does not exist
• 405 Method Not Allowed: HTTP method not supported for this endpoint
• 409 Conflict: Request conflicts with current state
• 422 Unprocessable Entity: Valid syntax but semantic errors
• 429 Too Many Requests: Rate limit exceeded

5xx - Server Error

The server failed to fulfill a valid request.

• 500 Internal Server Error: Generic server error
• 502 Bad Gateway: Invalid response from upstream server
• 503 Service Unavailable: Server temporarily overloaded or in maintenance
• 504 Gateway Timeout: Upstream server did not respond in time

Handling Status Codes in Code

const response = await fetch('/api/users');
switch (response.status) {
  case 200:
    const data = await response.json();
    break;
  case 401:
    redirectToLogin();
    break;
  case 404:
    showNotFound();
    break;
  case 429:
    await delay(retryAfter);
    retry();
    break;
  case 500:
    showServerError();
    break;
}

Best Practices for API Design

1. Use 201 for resource creation, not 200

2. Use 204 for successful deletions with no response body

3. Use 400 for validation errors with descriptive error messages

4. Use 401 vs 403 correctly: 401 = not authenticated, 403 = not authorized

5. Use 429 with Retry-After header for rate limiting

6. Avoid 200 for errors: Don't return 200 with an error message in the body

Common Misconceptions

• 302 vs 307: 302 may change POST to GET; 307 preserves the method
• 401 vs 403: 401 means "who are you?"; 403 means "I know who you are but you can't do this"
• 404 vs 410: 404 = might come back; 410 = permanently gone

Check our HTTP Status Codes Reference tool for a complete, searchable list.