The Core Conflict: Purists vs. Pragmatists
At the heart of almost every status code disagreement is a classic clash of engineering philosophies. On one side, you have the Purists. They believe in adhering as strictly as possible to the official specifications, known as RFCs (Request for Comments),
which define what each code is meant to do. For them, using a code for a purpose outside its documented definition is a cardinal sin that creates ambiguity and confusion. They argue that precision and standardization are what make the web work at scale. On the other side are the Pragmatists. They argue that the ultimate goal is not to pass a technical standards exam but to create an API that is easy and intuitive for other developers (the “clients”) to use. If bending a rule or defaulting to a more generic code makes the developer experience better, then that’s the right call. They believe the RFCs are guidelines, not unbreakable laws, and that the response body can always provide the necessary context that a status code might lack.
Battleground 1: Deleting Data (200 vs. 204)
Here’s a common scenario: a user deletes something, like a photo or a comment. The API needs to respond to confirm the deletion was successful. What code should it send back? A Purist might argue for `204 No Content`. The spec says this code is for successful requests that don't need to return a message body. The action worked, and there’s nothing more to say. It’s clean, efficient, and technically correct. A Pragmatist might counter by using `200 OK` and returning a representation of the object that was just deleted. Why? Because it can simplify things for the client-side developer. They might want to show a message like “You successfully deleted ‘My Vacation Photo.jpg’” or use the data to update the UI without another network request. The Pragmatist sees the `204` as technically right but practically less helpful.
Battleground 2: Handling Bad Data (400 vs. 422)
Imagine a user filling out a registration form. They send the data, but the email address is invalid. The server needs to reject it. The question is, which `4xx` (client error) code is appropriate? Many engineers default to `400 Bad Request`. It’s a general-purpose “you messed up” signal. However, a Purist will point out that `400` is technically for malformed *syntax*—like sending broken JSON. The user’s request, in this case, was syntactically perfect; it was the *semantic* value (the invalid email) that was the problem. For this, they’ll advocate for `422 Unprocessable Entity`. This code specifically means, “I understand what you sent, but I can't process it.” The Pragmatist fires back: who cares? Almost no automated client distinguishes between a `400` and a `422`. Just use `400` and include a clear error message in the response body. Using `422` adds complexity for a distinction that few developers will ever appreciate or act on.
Battleground 3: To Reveal or Conceal (403 vs. 404)
This debate touches on security. A user tries to access a resource they don't have permission to see—say, a private document at `api/documents/123`. Should the server respond with `403 Forbidden` or `404 Not Found`? The `403` code is direct. It tells the user, “This resource exists, but you are not allowed to access it.” The `404` code, however, is ambiguous. It could mean the resource doesn't exist, or it could be a deliberate choice to hide the resource’s existence from unauthorized users. Major platforms like GitHub use `404` in this way. If you try to access a private repository you don’t have access to, it gives you a `404`, not a `403`. The rationale is security through obscurity: don't even confirm to a potential attacker that a valuable resource exists at that URL. The counterargument is that this violates the principle of least astonishment; a developer might be confused, thinking a link is broken when it's really a permissions issue.
