{
    "api": "YAML JSON TOON Database",
    "version": "1.0.0",
    "format": "json",
    "dataset": {
        "id": 2821,
        "slug": "http-server-error-guide",
        "title": "HTTP Server Error Status Codes (5xx)",
        "description": "Guide to 5xx server error responses: diagnosing 500, 502, 503, 504 errors, retry strategies, and monitoring.",
        "summary": "A guide to 5xx server-error codes (500, 501, 502, 503, 504, 507 and 511) with causes, diagnosis steps, what a client should do and what a server owner should fix, plus a retry strategy and monitoring metrics.",
        "use_when": [
            "You are diagnosing a 5xx response or deciding how clients should retry.",
            "You are defining monitoring for server errors."
        ],
        "caveats": [
            "5xx codes do not say whether a request had effects; retry only idempotent requests or use idempotency keys.",
            "Retries without backoff and jitter can turn a partial outage into a full one."
        ],
        "related": [
            "http-client-error-guide",
            "http-status-codes-complete",
            "site-reliability-practices",
            "monitoring-logging-tools"
        ],
        "entry_count": 12,
        "fields": [
            {
                "section": "server_errors",
                "field": "code",
                "type": "integer",
                "example": "500"
            },
            {
                "section": "server_errors",
                "field": "name",
                "type": "string",
                "example": "Internal Server Error"
            },
            {
                "section": "server_errors",
                "field": "cause",
                "type": "string",
                "example": "Generic server-side error; unhandled exception,\u2026"
            },
            {
                "section": "server_errors",
                "field": "diagnosis",
                "type": "string",
                "example": "Check application logs, stack traces, error mon\u2026"
            },
            {
                "section": "server_errors",
                "field": "client_action",
                "type": "string",
                "example": "Retry after delay (exponential backoff). If per\u2026"
            },
            {
                "section": "server_errors",
                "field": "server_fix",
                "type": "string",
                "example": "Add error handling, validate inputs, ensure res\u2026"
            },
            {
                "section": "server_errors",
                "field": "example",
                "type": "string",
                "example": "Method not implemented (POST on endpoint that o\u2026"
            },
            {
                "section": "retry_strategy",
                "field": "*",
                "type": "object",
                "example": "{exponential_backoff,example_config,jitter,idempotency}"
            },
            {
                "section": "monitoring_metrics",
                "field": "*",
                "type": "array",
                "example": "[5 items]"
            }
        ],
        "category": "HTTP Status Codes",
        "category_slug": "http-status-codes",
        "tags": "http,server-errors,5xx,monitoring,retry,devops",
        "view_count": 36,
        "created_at": 1777673262,
        "updated_at": 1777673262
    },
    "data": {
        "server_errors": [
            {
                "code": 500,
                "name": "Internal Server Error",
                "cause": "Generic server-side error; unhandled exception, unexpected condition.",
                "diagnosis": "Check application logs, stack traces, error monitoring (Sentry, Datadog). Common causes: null pointer, DB connection failure, unhandled promise rejection.",
                "client_action": "Retry after delay (exponential backoff). If persists, contact support with request ID\/timestamp.",
                "server_fix": "Add error handling, validate inputs, ensure resources available, catch exceptions"
            },
            {
                "code": 501,
                "name": "Not Implemented",
                "cause": "Server does not support the functionality required to fulfill the request.",
                "example": "Method not implemented (POST on endpoint that only supports GET), feature flag disabled",
                "diagnosis": "Check API documentation; endpoint may be planned but not released",
                "client_action": "Use alternative endpoint or method; check docs for supported operations"
            },
            {
                "code": 502,
                "name": "Bad Gateway",
                "cause": "Server acting as gateway\/proxy received invalid response from upstream server.",
                "example": "Nginx proxy to PHP-FPM got malformed response, API gateway to microservice got 404\/invalid JSON",
                "diagnosis": "Check upstream service health, connectivity, response format; inspect proxy logs",
                "client_action": "Retry after short delay (upstream may be temporary); if persistent, contact API provider"
            },
            {
                "code": 503,
                "name": "Service Unavailable",
                "cause": "Server temporarily unable to handle request due to overload or maintenance.",
                "example": "Too many concurrent connections, server restarting, maintenance mode, auto-scaling cold start",
                "diagnosis": "Check server load (CPU\/memory), connection pool exhaustion, deployment status",
                "client_action": "Retry with exponential backoff (e.g., 1s, 2s, 4s, 8s); check status page for known outage",
                "server_fix": "Scale resources, enable connection queuing, implement graceful degradation, schedule maintenance windows"
            },
            {
                "code": 504,
                "name": "Gateway Timeout",
                "cause": "Gateway\/proxy did not receive timely response from upstream server.",
                "example": "Nginx proxy timeout after 60s, API gateway upstream slow query (>30s), slow third-party API",
                "diagnosis": "Check upstream service latency, database query performance, network connectivity, timeout configurations",
                "client_action": "Retry with longer delay (upstream may need recovery); consider breaking request into smaller chunks"
            },
            {
                "code": 507,
                "name": "Insufficient Storage",
                "cause": "Server unable to store representation (disk full, quota exceeded).",
                "example": "Upload fails because disk full, user storage quota exceeded, temp directory full",
                "diagnosis": "Check disk space (`df -h`), inode usage, storage quotas, cleanup old files",
                "server_fix": "Increase storage, implement cleanup policies, add monitoring alerts for disk space"
            },
            {
                "code": 511,
                "name": "Network Authentication Required",
                "cause": "Client needs to authenticate to gain network access (captive portal, proxy auth).",
                "example": "Wi-Fi hotspot login page, corporate proxy requiring credentials",
                "diagnosis": "Check if behind captive portal; client should redirect user to login page",
                "client_action": "Open browser to authenticate; client libraries should handle 511 by showing login URL"
            }
        ],
        "retry_strategy": {
            "exponential_backoff": "Wait = min(2^n * base, max_delay) where n = attempt number (starting at 0)",
            "example_config": {
                "initial_delay_ms": 1000,
                "max_delay_ms": 60000,
                "multiplier": 2,
                "max_retries": 5
            },
            "jitter": "Add random \u00b110-25% to prevent thundering herd",
            "idempotency": "Only retry idempotent methods (GET, PUT, DELETE, HEAD, OPTIONS); POST should be retried only with idempotency key"
        },
        "monitoring_metrics": [
            "Error rate percentage (5xx \/ total requests)",
            "P99\/P95 latency of error responses",
            "Upstream service health checks",
            "Server resource metrics (CPU, memory, disk, connections)",
            "Circuit breaker state (open\/closed\/half-open)"
        ]
    }
}