api: YAML JSON TOON Database
version: 1.0.0
format: yaml
dataset:
  id: 421
  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: 2
  created_at: 1781275786
  updated_at: 1781275786
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