What are client error status codes?

"You made a mistake"

Imagine you walk into a library and ask for a book that doesn't exist. The librarian doesn't apologize: it's not the library's fault. They tell you: "We don't have that book." That's the spirit of a 4xx status code.

When a server responds with a 4xx status code, it's saying: "There's a problem with YOUR request. I understood what you sent, but I can't or won't process it." The error is on the client's side: bad URL, missing credentials, invalid data, or something else the client did wrong.

Client errors vs. server errors

HTTP status codes in the 4xx range mean the client made an error. Codes in the 5xx range mean the server made an error. This distinction matters:

Why does this matter for developers?

• 4xx errors mean your code should guide the user to fix their request (show a "page not found" message, highlight invalid form fields, prompt for login)
• 5xx errors mean your code has a bug or your infrastructure has a problem: the user can't fix it

The 4xx family at a glance

The 4xx range has many codes, but a handful appear in almost every web application:

We'll focus on the most important ones throughout this course.

The anatomy of a 4xx response

A good 4xx response does more than just say "error." It tells the client what went wrong and how to fix it:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "errors": {
    "email": ["is not valid"],
    "password": ["is too short (minimum is 8 characters)"]
  }
}

Compare that to a unhelpful response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Error

The first response tells the client what to fix. The second leaves them guessing. Always aim for the first approach.

4xx in the browser

When a browser encounters a 4xx error, what the user sees depends on the application:

Without custom error handling:
The user gets a bare default page: a framework's stock page (Rails ships public/404.html) or the web server's plain "404 Not Found". Only when the body is empty does the browser show its own error page.

With custom error handling:
The application renders a friendly error page with helpful information, navigation links, and maybe a search bar to help the user find what they were looking for.

Professional applications always implement custom error pages. A well-designed 404 page can turn a frustrating experience into a positive one.

Common misconceptions

"401 means the user doesn't have permission"

No: 401 means the user hasn't identified themselves (not logged in). If they're logged in but lack permission, that's 403 Forbidden. We'll cover this distinction in detail in Lesson 3.

"422 and 400 are the same thing"

They're related but different. 400 means the request is malformed (the server can't even parse it). 422 means the request is well-formed but the data is invalid (like submitting an email without an @ sign). We'll explore this in Lesson 5.

"404 means something is broken"

Not necessarily. A 404 means the resource doesn't exist at that URL. It could be a typo, a deleted page, or a URL that never existed. It's the most common and most normal error on the web.

When to return which code

Choosing the right 4xx code makes your API and application easier to understand and debug:

flowchart TB
  A{"Is the request malformed?"} -->|"yes"| A1["400 Bad Request"]
  A -->|"no"| B{"Is the user authenticated?"}
  B -->|"no"| B1["401 Unauthorized"]
  B -->|"yes"| C{"Does the user have permission?"}
  C -->|"no"| C1["403 Forbidden"]
  C -->|"yes"| D{"Does the resource exist?"}
  D -->|"no"| D1["404 Not Found"]
  D -->|"yes"| E{"Is the data valid?"}
  E -->|"no"| E1["422 Unprocessable Content"]
  E -->|"yes"| F["Process the request (2xx)"]

This decision tree will become second nature as you build more applications.

Summary