HTTP Status Codes

# CHAPTER 7

HTTP Status Codes #

1. Introduction #

2. Learning Objectives #

• Explain the 5 different classes of HTTP status codes (1xx, 2xx, 3xx, 4xx, 5xx).

• Use standard 2xx codes to indicate success.

• Differentiate between 401 Unauthorized and 403 Forbidden.

• Understand the proper use of 404 Not Found in an API context.

• Implement HTTP status codes in a PHP API response.

3. Beginner-Friendly Explanation #

• 200s (Green Light): Success! Everything went perfectly.

• 300s (Yellow Light / Detour): Redirection. The thing you want is somewhere else.

• 400s (Red Light - Driver's Fault): Client Error. You asked for something that doesn't exist, you typed it wrong, or you don't have permission. It's your fault.

• 500s (Red Light - Road Closed): Server Error. The server crashed, the database is down, or there is a bug in the code. It's the server's fault.

4. Real-World Examples #

• 404 Not Found: You click a dead link on a website, and a funny page pops up saying "Oops, this page doesn't exist." That's a 404.

• 401 Unauthorized: You try to access a private dashboard without logging in, and the site kicks you back to the login page.

• 500 Internal Server Error: A website is completely broken because the developers accidentally introduced a bug that crashes the database connection.

5. Detailed Code Examples #

<?php
// A simple API endpoint demonstrating status codes
$userId = $_GET[&#039;id'] ?? null;

if (!$userId) {
    // Client didn't provide an ID - Client error!
    http_response_code(400); 
    echo json_encode(["error" => "User ID is required (Bad Request)"]);
    exit;
}

// Simulate database lookup
if ($userId == 5) {
    // Success!
    http_response_code(200);
    echo json_encode(["id" => 5, "name" => "Sarah"]);
} else {
    // ID provided, but not found in database
    http_response_code(404);
    echo json_encode(["error" => "User not found"]);
}
?>

6. Request/Response Examples #

Response:

HTTP/1.1 201 Created
Location: /users/99
Content-Type: application/json

{
  "message": "User successfully created",
  "user_id": 99
}

7. HTTP Examples #

• 200 OK: Standard success. (GET, PUT, PATCH)

• 201 Created: Success, and a new resource was created. (POST)

• 204 No Content: Success, but there is no data to return. (Often used for DELETE)

• 400 Bad Request: The JSON sent by the client was invalid or missing fields.

• 401 Unauthorized: The client didn't provide an API token, or the token is invalid.

• 403 Forbidden: The client provided a valid token, but that user doesn't have admin rights to do this action.

• 404 Not Found: The URL is wrong, or the specific resource ID doesn't exist.

• 500 Internal Server Error: A generic catch-all for when the PHP script crashes.

8. JSON Examples #

{
  "error": {
    "code": 403,
    "message": "Forbidden. You must be an administrator to delete posts.",
    "documentation_url": "https://api.docs.com/errors#403"
  }
}

9. Best Practices #

• Never return a 200 OK for an error: Some bad APIs always return a 200 status code, but put "error": true in the JSON. This is an anti-pattern. Always use the proper HTTP status code so automated tools and libraries know the request failed without having to parse the JSON.

• Keep it simple: You don't need to use all 60+ status codes. Stick to the common ones (200, 201, 204, 400, 401, 403, 404, 500) and you will cover 99% of use cases.

10. Common Mistakes #

• Confusing 401 and 403:

• 401 = "I don't know who you are. Go log in." (Authentication issue)

• 403 = "I know exactly who you are, but you are a standard user and this is an admin action." (Authorization issue)

• Leaking info in 500 errors: When a 500 error happens, never output the raw PHP SQL error to the client, as hackers can use this to understand your database structure. Return a generic message instead.

11. Mini Exercises #

1. 1. What status code would you return if a user tries to POST JSON, but they forgot a closing bracket so the JSON is completely unreadable?

1. 2. What status code would you return if an API request is made to /users/999, but there are only 50 users in the database?

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain the difference between 401 Unauthorized and 403 Forbidden.

• Q: Why is it considered bad practice to return a 200 OK status code with an error message in the JSON body?

• Q: In what scenario would an API appropriately return a 204 No Content status code?

15. FAQs #

Q: I saw a 418 I'm a teapot code. Is that real? A: Yes, but it's an internet joke. It was created as an April Fools' joke by the IETF in 1998, though some servers actually implement it as an Easter egg!

16. Summary #

17. Next Chapter Recommendation #