Stage 4. Response Status Codes

An HTTP status code is the first result signal a client receives, even before parsing the response body. In API systems this is critical: mobile apps, frontend clients, retry logic, monitoring, and alerts all react to that code. Because of that, status codes are part of the API contract, not a cosmetic detail.

Status codes map

1. The Core Grouping Model

For practical work, three groups explain most real cases:

2xx: request was processed successfully.
4xx: problem in client request, access rights, or request context.
5xx: server-side failure.

This simple model already improves troubleshooting. If 4xx rates increase, investigate validation, permissions, and client flows. If 5xx rises, inspect backend stability and downstream dependencies.

2. Minimal Status Set You Should Master First

Code	When to use it	What the client should understand
`200 OK`	Successful read or update with response body	Operation succeeded; body data can be consumed
`201 Created`	New resource created successfully	Resource exists now, often with `id` and/or `Location`
`204 No Content`	Success with no response payload needed	Operation succeeded; no body parsing required
`400 Bad Request`	Request format is invalid	Request must be technically fixed
`401 Unauthorized`	Missing or invalid authentication	Re-authentication or token refresh is needed
`403 Forbidden`	Authenticated user lacks required permission	Login retry will not solve it; access rights are needed
`404 Not Found`	Resource does not exist at requested path	Target object is unavailable or absent
`409 Conflict`	Request conflicts with current resource state	Operation is logically blocked by current state
`422 Unprocessable Entity`	JSON is syntactically valid but breaks business rules	Field values must be corrected according to domain rules
`500 Internal Server Error`	Unexpected server failure	Problem is on backend side

For beginner-to-intermediate API development, this set is enough. There is no need to memorize many rare codes before facing a specific use case.

3. High-Value Distinctions Developers Often Mix Up

401 versus 403 is the most common confusion. 401 means authentication is missing, expired, or invalid. 403 means the user is authenticated but not allowed to perform the action. This directly affects UX: the first case should drive login/token refresh, the second should show an access-denied flow.

400 versus 422 is another important distinction. 400 means the request is technically malformed, such as broken JSON syntax or wrong structural shape. 422 means syntax is valid, but business validation failed, for example weak password or invalid date range.

4. Status Code and Error Body Must Reinforce Each Other

Status code gives the error class; response body gives the details needed by humans and machines.

{
  "error": "validation_failed",
  "message": "password is too weak",
  "fields": {
    "password": "min 12 chars, at least one digit"
  },
  "traceId": "c92ab1d4"
}

If this error schema is consistent across endpoints, clients can implement one reusable handler instead of endpoint-specific exception branches.

5. Why “Always Return 200” Is Harmful

Some teams return 200 OK for every outcome and place failure flags such as success=false in the body. This breaks protocol semantics: monitoring counts failures as success, retry behavior becomes unreliable, and clients must implement custom parsing logic instead of standard HTTP handling. In production, this increases complexity and maintenance cost.

6. Practical Scenario: User Registration Endpoint

Consider a single endpoint: POST /users.

Valid request, user created: return 201 Created.
Email already exists: return 409 Conflict.
Email format invalid or password fails policy: return 422 Unprocessable Entity.
JSON syntax is broken: return 400 Bad Request.
Database is unavailable: return 500 Internal Server Error.

In this flow, each code maps to a different problem class, so client behavior is predictable: ask user to fix fields, show duplicate-email feedback, suggest retry later, or route to authentication recovery when needed.

7. Release Checklist for a New Endpoint

Does each major outcome have a distinct and logical status code?
Is the border between 400 and 422 clear?
Are 401 and 403 used according to authentication vs authorization rules?
Is error-body structure consistent across related endpoints?
Do automated tests protect status behavior from accidental refactor regressions?

Http Response Statuses