HTTP Status Codes

Every HTTP response starts with a status code: a three-digit number that tells the client what happened. Browsers, search engines and API clients all rely on it.

The five groups

The codes you will use

Sending a status code in PHP

1
2
3

<?php
http_response_code(404);
echo "Page not found";

Call it before output, and remember that the code is part of the headers.

1
2
3

<?php
http_response_code(201);
header("Location: /products/42");   // where the new resource is

For redirects, header("Location: ...") sets 302 automatically. To choose, pass the code as the third argument: header("Location: /new", true, 301).

Why correct codes matter

• Search engines. A missing page that returns 200 (a “soft 404”) confuses search engines. A moved page should return 301.
• Clients. A JavaScript fetch() treats 404 and 500 differently from 200, and can react.
• Monitoring. Tools count 5xx responses to find outages.

Choose between 401, 403 and 404

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<?php
function statusFor(bool $loggedIn, bool $allowed, bool $exists): int
{
    if (!$loggedIn) {
        return 401;
    }

    if (!$exists) {
        return 404;
    }

    return $allowed ? 200 : 403;
}

echo statusFor(false, false, true) . " ";
echo statusFor(true, false, true) . " ";
echo statusFor(true, true, false) . " ";
echo statusFor(true, true, true);

1

401 403 404 200

Sometimes you return 404 instead of 403 on purpose, so that people cannot find out which private resources exist.

400 vs 422

• 400: the request itself is broken (invalid JSON, missing required header).
• 422: the JSON is fine, but a value is not acceptable (an invalid email). Many APIs simply use 400 for both. Be consistent.

Names for codes

1
2
3
4
5
6

<?php
$names = [200 => "OK", 201 => "Created", 404 => "Not Found", 500 => "Internal Server Error"];

foreach ([201, 404] as $code) {
    echo "$code {$names[$code]}\n";
}

1
2

201 Created
404 Not Found

Read a status code

When you call another API, check the status before you trust the body. API Error Handling shows how.