HTTP Status Code Checker: Test URL Response Codes

# Get just the numeric status code (discard body and headers)
curl -o /dev/null -s -w "%{http_code}
" https://example.com
# Output: 200

# Get all response headers (HEAD request — faster, no body)
curl -I https://example.com
# HTTP/2 200
# content-type: text/html; charset=UTF-8
# ...

# Follow redirects and show the final URL + status code
curl -s -o /dev/null -w "%{url_effective} %{http_code}
" -L https://example.com/old-path
# https://example.com/new-path 200

# Full redirect chain (shows headers at each hop)
curl -I -L --max-redirs 10 https://example.com/redirect-me
# HTTP/1.1 301 Moved Permanently
# Location: https://example.com/step-two
# ...
# HTTP/1.1 302 Found
# Location: https://example.com/final
# ...
# HTTP/2 200

# Extract multiple metrics in one request
curl -o /dev/null -s -w "status=%{http_code} time=%{time_total}s size=%{size_download}b
"   https://example.com
# status=200 time=0.125s size=1256b

# Test with a specific HTTP method (useful for API health checks)
curl -o /dev/null -s -w "%{http_code}
" -X POST   -H 'Content-Type: application/json'   --data-raw '{"ping":true}'   https://api.example.com/health

import requests
from concurrent.futures import ThreadPoolExecutor
from typing import NamedTuple

class UrlStatus(NamedTuple):
    url: str
    status_code: int
    final_url: str  # After redirects
    elapsed_ms: float

def check_url(url: str, timeout: int = 10) -> UrlStatus:
    """Check a URL's HTTP status code without downloading the full body."""
    try:
        # Use stream=True to avoid downloading large bodies
        response = requests.get(url, timeout=timeout, stream=True,
                                allow_redirects=True)
        return UrlStatus(
            url=url,
            status_code=response.status_code,
            final_url=response.url,
            elapsed_ms=response.elapsed.total_seconds() * 1000,
        )
    except requests.exceptions.Timeout:
        return UrlStatus(url=url, status_code=408, final_url=url, elapsed_ms=timeout*1000)
    except requests.exceptions.ConnectionError:
        return UrlStatus(url=url, status_code=0, final_url=url, elapsed_ms=0)
    finally:
        if 'response' in dir():
            response.close()

# Bulk URL checker with thread pool
def check_urls(urls: list[str], max_workers: int = 10) -> list[UrlStatus]:
    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        return list(executor.map(check_url, urls))

# Usage
urls = [
    "https://example.com",
    "https://example.com/page-that-might-be-gone",
    "https://api.example.com/health",
]
results = check_urls(urls)
for r in results:
    symbol = "✓" if 200 <= r.status_code < 300 else "✗"
    print(f"{symbol} [{r.status_code}] {r.url} → {r.final_url} ({r.elapsed_ms:.0f}ms)")

interface UrlResult {
  url: string
  statusCode: number | null
  finalUrl: string
  redirectCount: number
  error?: string
}

async function checkUrl(url: string, timeoutMs = 10_000): Promise<UrlResult> {
  const controller = new AbortController()
  const timer = setTimeout(() => controller.abort(), timeoutMs)

  try {
    const response = await fetch(url, {
      signal: controller.signal,
      redirect: 'follow',  // Follow redirects (default)
    })

    // Count redirects via response.redirected (bool) — for full chain, use manual redirect
    return {
      url,
      statusCode: response.status,
      finalUrl: response.url,
      redirectCount: response.redirected ? 1 : 0,  // fetch API doesn't count hops
    }
  } catch (err) {
    const error = err instanceof Error ? err.message : String(err)
    const isTimeout = error.includes('abort') || error.includes('timeout')
    return {
      url,
      statusCode: isTimeout ? 408 : null,
      finalUrl: url,
      redirectCount: 0,
      error,
    }
  } finally {
    clearTimeout(timer)
  }
}

// Check multiple URLs concurrently (batch to avoid overwhelming servers)
async function checkUrlsBatch(urls: string[], batchSize = 10): Promise<UrlResult[]> {
  const results: UrlResult[] = []
  for (let i = 0; i < urls.length; i += batchSize) {
    const batch = urls.slice(i, i + batchSize)
    const batchResults = await Promise.all(batch.map(checkUrl))
    results.push(...batchResults)
  }
  return results
}

// Wrong: HTTP 200 with error body
HTTP/1.1 200 OK
{"success": false, "error": "card_declined", "code": "PAYMENT_FAILED"}

// Correct: HTTP 402 Payment Required (or 422 Unprocessable Entity)
HTTP/1.1 402 Payment Required
{
  "error": {
    "code": "card_declined",
    "message": "Your card was declined. Please try a different payment method.",
    "type": "payment_error",
    "decline_code": "insufficient_funds"
  }
}

// 401 Unauthorized — semantically means "UNAUTHENTICATED"
// Use when: no credentials provided, or credentials are invalid
// Requires: WWW-Authenticate header in the response
// Client action: present credentials (log in, include auth token)
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api.example.com"

// 403 Forbidden — semantically means "UNAUTHORIZED" (lacks permission)
// Use when: credentials are valid, but the user lacks the required role/scope
// No WWW-Authenticate header needed
// Client action: request elevated permissions, contact administrator
HTTP/1.1 403 Forbidden
{"error": "You need the 'admin' role to access this resource"}

// Decision tree:
// Is the user logged in / authenticated?
//   No  → 401 (with WWW-Authenticate)
//   Yes → Is the resource they're accessing within their permission scope?
//           No  → 403
//           Yes → allow access

// 400 Bad Request: the request is syntactically malformed
// Use for: invalid JSON, missing required headers, malformed URL parameters
// The server can't parse the request at all
HTTP/1.1 400 Bad Request
{"error": "Invalid JSON: unexpected token at position 42"}

// 422 Unprocessable Entity: syntactically valid but semantically wrong
// Use for: valid JSON that fails business logic validation
// The server understood the request but can't process it
HTTP/1.1 422 Unprocessable Entity
{
  "error": "Validation failed",
  "fields": {
    "email": "Already registered",
    "age": "Must be 18 or older",
    "start_date": "Cannot be in the past"
  }
}

// Practical rule:
// 400 = parser error (couldn't even deserialize the request)
// 422 = validation error (deserialized successfully, but values are invalid)

// 301 Moved Permanently: historically allowed clients to change POST to GET
// Some HTTP/1.0 clients DID silently change POST→GET on 301 redirects
// RFC 9110 acknowledges this historical behavior remains common

// For API redirects, always use 307 or 308 — they GUARANTEE method preservation
// 307 Temporary Redirect: same method, but check original URL on next request
// 308 Permanent Redirect: same method, update bookmarks/links

// Example: renaming an API endpoint without breaking clients
// Old: POST /api/v1/order  →  New: POST /api/v2/orders

# Wrong: might silently change POST to GET
HTTP/1.1 301 Moved Permanently
Location: https://api.example.com/v2/orders

# Correct: guarantees POST is preserved
HTTP/1.1 308 Permanent Redirect
Location: https://api.example.com/v2/orders

# Browser note: 301/302 are fine for HTML page redirects
# where changing GET→GET doesn't matter and search engines need to update indexes

# Show full redirect chain with timing at each hop
curl -s -o /dev/null -w "Code: %{http_code} | URL: %{url_effective}
"   -L --max-redirs 10 https://example.com/old

# Verbose headers at each hop (shows Location headers)
curl -vL --max-redirs 10 https://example.com/old 2>&1 | grep -E '^< (HTTP|Location)'

# Python: map the full redirect chain
import requests

def trace_redirects(url: str) -> list[dict]:
    """Return every hop in the redirect chain, including the final destination."""
    session = requests.Session()
    # Disable auto-redirect so we can see each step
    response = session.get(url, allow_redirects=False, timeout=10)

    chain = []
    while response.is_redirect:
        chain.append({
            "url": url,
            "status": response.status_code,
            "location": response.headers.get("Location", ""),
        })
        url = response.headers["Location"]
        response = session.get(url, allow_redirects=False, timeout=10)

    chain.append({"url": url, "status": response.status_code, "location": None})
    return chain

hops = trace_redirects("https://bit.ly/example")
for i, hop in enumerate(hops):
    print(f"  {i+1}. [{hop['status']}] {hop['url']}")

#!/bin/bash
# Simple uptime monitor — run via cron: */1 * * * * /path/to/monitor.sh

ENDPOINTS=(
    "https://api.example.com/health"
    "https://app.example.com/"
    "https://api.example.com/v1/status"
)

ALERT_EMAIL="[email protected]"
TIMEOUT=10

for url in "${ENDPOINTS[@]}"; do
    # -o /dev/null: discard body
    # -s: silent mode (no progress bar)
    # -w "%{http_code}": write just the status code
    # --max-time: total timeout
    status=$(curl -o /dev/null -s -w "%{http_code}" --max-time $TIMEOUT "$url")

    if [[ "$status" != 2* ]]; then
        # Non-2xx response — send alert
        echo "ALERT: $url returned HTTP $status at $(date -u)" |             mail -s "Uptime Alert: $url" "$ALERT_EMAIL"
        logger -t uptime-monitor "FAILED: $url returned HTTP $status"
    else
        logger -t uptime-monitor "OK: $url returned HTTP $status"
    fi
done