api: YAML JSON TOON Database
version: 1.0.0
format: toon
dataset:
  id: 2809
  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[2]: You are designing error responses for an API.,You need to pick between similar 4xx codes.
  caveats[2]: 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[4]: http-status-codes-complete,http-server-error-guide,http-status-code-best-practices,http-authentication-methods
  entry_count: 9
  fields[8]{section,field,type,example}:
    client_errors,code,integer,"400"
    client_errors,name,string,Bad Request
    client_errors,cause,string,"Malformed syntax, invalid request message frami…"
    client_errors,example,string,"Missing required JSON field, invalid JSON synta…"
    client_errors,response_body,string,"{\"error\": \"Invalid input\", \"field\": \"email\", \"m…"
    client_errors,notes,string,Server cannot or will not process request due t…
    client_errors,response_headers,string,"WWW-Authenticate: Bearer realm=\"api\""
    error_response_format,*,object,"{standard_fields,example,security_notes}"
  category: HTTP Status Codes
  category_slug: http-status-codes
  tags: "http,client-errors,4xx,error-handling,security,rate-limiting"
  view_count: 42
  created_at: 1777673262
  updated_at: 1777673262
data:
  client_errors[9]:
    - 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"