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."
  summary: "A guide to the common 4xx client-error status codes: 400, 401, 403, 404, 405, 408, 409, 429 and 431, each with its cause, an example, a response body and notes, plus a standard error-response format and security notes."
  use_when:
    - You are designing error responses for an API.
    - You need to pick between similar 4xx codes.
  caveats:
    - Error bodies should be machine-readable but must not leak internal detail or secrets.
    - Using one generic 400 for everything loses information that clients and monitors can use.
  related:
    - http-status-codes-complete
    - http-server-error-guide
    - http-status-code-best-practices
    - http-authentication-methods
  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
  entry_count: 9
  fields:
    - section: client_errors
      field: code
      type: integer
      example: "400"
    - section: client_errors
      field: name
      type: string
      example: Bad Request
    - section: client_errors
      field: cause
      type: string
      example: Malformed syntax, invalid request message frami…
    - section: client_errors
      field: example
      type: string
      example: Missing required JSON field, invalid JSON synta…
    - section: client_errors
      field: response_body
      type: string
      example: "{\"error\": \"Invalid input\", \"field\": \"email\", \"m…"
    - section: client_errors
      field: notes
      type: string
      example: Server cannot or will not process request due t…
    - section: client_errors
      field: response_headers
      type: string
      example: "WWW-Authenticate: Bearer realm=\"api\""
    - section: error_response_format
      field: "*"
      type: object
      example: "{standard_fields,example,security_notes}"
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