HTTP Status Codes: What They Mean and When to Use Them

Your API returns 200. The response body says {"error": "Not found"}.

This is wrong. Status codes exist for a reason. Use them properly.

The Five Categories

1xx — Informational. Rarely seen in practice.

2xx — Success. The request worked.

3xx — Redirection. Go somewhere else.

4xx — Client error. You did something wrong.

5xx — Server error. We did something wrong.

The Codes You'll Actually Use

Success (2xx)

200 OK — Standard success. Use for GET requests that return data.

201 Created — Resource was created. Use after successful POST that creates something.

204 No Content — Success, but nothing to return. Use for DELETE or updates that don't return data.

Client Errors (4xx)

400 Bad Request — Malformed request. Invalid JSON, missing required fields, wrong data types.

401 Unauthorized — No authentication. User needs to log in.

403 Forbidden — Authenticated but not allowed. User exists but lacks permission.

404 Not Found — Resource doesn't exist. The classic.

409 Conflict — Request conflicts with current state. Duplicate username, version mismatch.

422 Unprocessable Entity — Syntactically correct but semantically wrong. Valid JSON but business rules violated.

429 Too Many Requests — Rate limited. Slow down.

Server Errors (5xx)

500 Internal Server Error — Generic server failure. Something crashed.

502 Bad Gateway — Upstream server failed. Your server is fine, but something it depends on isn't.

503 Service Unavailable — Temporarily down. Maintenance or overload.

504 Gateway Timeout — Upstream server didn't respond in time.

Common Mistakes

200 with error in body. If it's an error, use an error status code. Don't make clients parse the body to know if it succeeded.

500 for validation errors. User submitted bad data? That's 400 or 422, not 500. Server isn't broken—the request is.

401 vs 403 confusion. 401 means "who are you?" 403 means "I know who you are, but no."

404 for everything. "Not found" isn't always the right answer. Wrong method? 405. Rate limited? 429.

Designing APIs

Be specific. Clients can handle specific errors intelligently. Generic errors mean generic handling.

Include error details in the body:

{
  "error": "validation_failed",
  "message": "Email format is invalid",
  "field": "email"
}

The status code says what category of problem. The body explains specifically.

Handling Status Codes as a Client

2xx — Parse the response, proceed normally.

4xx — Your fault. Log, display to user, fix the request.

5xx — Server's fault. Maybe retry with backoff. Maybe alert.

3xx — Follow redirects automatically (most HTTP clients do).

Don't just check for 200. Check for success (2xx) and handle other cases appropriately.

---

Status codes are communication. Use them correctly and APIs become self-documenting. Misuse them and debugging becomes guesswork.