HTTP Status Codes That Tell the Truth¶

Status codes are how your API communicates what happened. Using the right one makes clients robust; lying with 200 OK on everything makes them fragile.

The Codes You'll Use Daily¶

Map CRUD to Codes¶

POST /tasks → 201 (Location: /tasks/:id) or 400/422 GET /tasks/:id → 200 or 404 PUT /tasks/:id → 200 or 404 or 400 DELETE /tasks/:id → 204 or 404

401 vs 403 — Know the Difference¶

• 401 Unauthorized — "I don't know who you are." (Not logged in.)
• 403 Forbidden — "I know who you are, and you can't do this." (Logged in, wrong permissions.)

400 vs 404 vs 409¶

• 400/422 — the request is wrong (bad body, invalid field).
• 404 — the resource isn't there.
• 409 — the request conflicts with current state (e.g. creating a duplicate).

Don't Leak Existence¶

Sometimes returning 404 instead of 403 is intentional — you don't want to reveal that a record exists to someone not allowed to see it. Security and status codes interact; we revisit this in Chapter 7.