{
    "api": "YAML JSON TOON Database",
    "version": "1.0.0",
    "format": "json",
    "dataset": {
        "id": 23,
        "slug": "http-client-error-guide",
        "title": "HTTP Client Error Status Codes (4xx)",
        "description": "Guide to 4xx client error responses: when to use 400 vs 401 vs 403 vs 404 vs 429, proper error responses, and user experience.",
        "category": "HTTP Status Codes",
        "category_slug": "http-status-codes",
        "tags": "http,client-errors,4xx,error-handling,security,rate-limiting",
        "view_count": 0,
        "created_at": 1777673262,
        "updated_at": 1777673262
    },
    "data": {
        "client_errors": [
            {
                "code": 400,
                "name": "Bad Request",
                "cause": "Malformed syntax, invalid request message framing, or deceptive request routing.",
                "example": "Missing required JSON field, invalid JSON syntax, query parameter type mismatch",
                "response_body": "{\"error\": \"Invalid input\", \"field\": \"email\", \"message\": \"Email format invalid\"}",
                "notes": "Server cannot or will not process request due to client error (not server fault)"
            },
            {
                "code": 401,
                "name": "Unauthorized",
                "cause": "Request requires user authentication; credentials missing or invalid.",
                "example": "No Authorization header, expired JWT, invalid API key",
                "response_headers": "WWW-Authenticate: Bearer realm=\"api\"",
                "notes": "Do not use for missing permissions (use 403); client may retry with credentials"
            },
            {
                "code": 403,
                "name": "Forbidden",
                "cause": "Server understood request but refuses to authorize; valid credentials but insufficient permissions.",
                "example": "User role lacks access to admin endpoint, IP blocked, account suspended",
                "response_body": "{\"error\": \"Access denied\", \"reason\": \"insufficient_privileges\"}",
                "notes": "Never expose why access denied in production (security through obscurity); log details server-side"
            },
            {
                "code": 404,
                "name": "Not Found",
                "cause": "Requested resource does not exist on server.",
                "example": "Non-existent URL path, deleted resource, typo in endpoint",
                "notes": "Do not reveal whether resource exists (prevents user enumeration); return generic message"
            },
            {
                "code": 405,
                "name": "Method Not Allowed",
                "cause": "Request method not supported for target resource.",
                "example": "GET on /api/users (expects POST), DELETE on read-only endpoint",
                "response_headers": "Allow: POST, PUT",
                "notes": "Include Allow header listing supported methods"
            },
            {
                "code": 408,
                "name": "Request Timeout",
                "cause": "Server did not receive complete request in time it was prepared to wait.",
                "example": "Client slow-down; slow POST body upload, client closed connection prematurely",
                "notes": "May be retried by client with exponential backoff; distinguish from 504 (server timeout)"
            },
            {
                "code": 409,
                "name": "Conflict",
                "cause": "Request conflicts with current state of resource; cannot be completed.",
                "example": "Editing stale version (optimistic concurrency), duplicate unique key, file lock conflict",
                "response_body": "{\"error\": \"Conflict\", \"detail\": \"Version mismatch; resource modified by others\"}",
                "notes": "Include details about conflict in body so client can resolve (e.g., current version)"
            },
            {
                "code": 429,
                "name": "Too Many Requests",
                "cause": "User sent too many requests in given time (rate limiting).",
                "example": "Exceeded 100 requests/minute limit, burst limit exceeded",
                "response_headers": "Retry-After: 60 (seconds)",
                "notes": "Include Retry-After header; implement exponential backoff on client"
            },
            {
                "code": 431,
                "name": "Request Header Fields Too Large",
                "cause": "Server unwilling to process request due to individual header fields too large.",
                "example": "Cookie header exceeds 4KB, extremely long User-Agent, huge custom header",
                "notes": "Often due to oversized cookies; consider clearing cookies or session reset"
            }
        ],
        "error_response_format": {
            "standard_fields": ["error", "message", "details", "code", "timestamp"],
            "example": {
                "error": "invalid_input",
                "message": "The provided email address is not valid.",
                "field": "email",
                "value": "not-an-email",
                "documentation_url": "https://api.example.com/docs/errors#INVALID_EMAIL"
            },
            "security_notes": "Never leak internal error messages, stack traces, SQL, file paths, or server configuration in production errors"
        }
    }
}