HTTP Status Codes Every Developer Should Know

What You'll Learn

• The five families of HTTP status codes (1xx–5xx)
• The specific codes you will see in real API work
• How to choose the right success code for your API
• How to read error codes to debug faster

Why This Matters

Every HTTP response starts with a status code. It is the single most important piece of information in the response — it tells you whether your request worked, failed, or something in between. If you do not know what 401 vs 403 vs 422 mean, you will misdiagnose every API problem.

The Five Families

Status codes are three-digit numbers. The first digit tells you the family:

Success Codes (2xx)

The four you'll see daily

• 200 OK — "here's what you asked for"
• 201 Created — "I made the new thing you asked for"
• 204 No Content — "I did what you asked; nothing to return"
• 202 Accepted — "I'll do this later; check back"

Redirection Codes (3xx)

Most APIs avoid 3xx — they prefer to return the resource directly or use a clear 404. But 304 is common in APIs that support caching via If-None-Match and ETag headers.

Client Error Codes (4xx)

This is the family you will spend the most time on. Every 4xx means the client did something wrong.

The 401 vs 403 distinction

This is the most-misunderstood pair:

• 401 Unauthorized: "I don't know who you are." Missing or invalid token. Solution: authenticate.
• 403 Forbidden: "I know who you are, but you can't do this." Valid token, but no permission. Solution: request access from an admin.

If you are logged in but cannot delete a post, that is 403, not 401. If your token expired and the server does not recognize you, that is 401, not 403.

400 vs 422

• 400 Bad Request: The request itself is malformed — invalid JSON, missing Content-Type, broken syntax.
• 422 Unprocessable Entity: The request is well-formed JSON, but the values fail business rules (e.g., email: "not-an-email").

Many APIs use 400 for both cases. Strictly speaking, 422 is more accurate when the JSON parses but fails validation.

Server Error Codes (5xx)

5xx means the server failed. The client's request was valid; the server could not handle it.

What 5xx tells you as a client

5xx errors are usually not your fault. Retry with backoff, and if they persist, check the API's status page or contact the provider.

Common Mistakes

1. Returning 200 for everything. Some APIs return 200 with an error in the body. This breaks standard HTTP clients and tools. Use the right status code.
2. Using 401 for permission errors. If the user is authenticated but lacks permission, that is 403, not 401.
3. Using 404 to hide authorization failures. Some APIs return 404 instead of 403 to avoid leaking that a resource exists. This is a deliberate security choice but should be documented.
4. Treating 5xx as the client's fault. 5xx is the server's problem. Don't try to "fix" your request — retry with backoff.
5. Forgetting the Location header with 201. 201 Created should include a Location header pointing to the new resource's URL.

Practical Exercise (5 minutes)

Match each scenario to its correct status code:

1. You send a POST with malformed JSON.
2. You request a user ID that does not exist.
3. You forgot to send your auth token.
4. You send a valid token but try to delete another user's post.
5. The server's database crashed mid-request.
6. You successfully created a new user.
7. You sent 100 requests in 10 seconds and the API blocked you.

Answers: 1→400, 2→404, 3→401, 4→403, 5→500, 6→201, 7→429.

Mini Challenge

Open the JSONPlaceholder API and trigger three different status codes intentionally: a 200 (GET any post), a 404 (GET a non-existent post ID like 999999), and a 201 (POST a new post). Use curl -i so you can see the status line.

Key Takeaways