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:
      [5]: 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"