# Status Codes and Headers

A response's three-digit status code tells the app how its request went before it reads a word of the body, its first digit names the family (2xx it worked, 3xx look elsewhere, 4xx the request has a problem, 5xx the server broke), and headers such as Content-Type tell the app how to read the body.

Apprentice · REST API · Web Development · Python · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Choose the status code an API should send for a situation, such as 200, 201, 204, 400, 404, 409, 422 or 500, and read it as a sentence
- Explain what a header tells the other side, such as the Content-Type that says a body is JSON

## Key takeaways

- An app reads the status code first. An API that answers 200 to everything, errors included, leaves the app guessing from the words in the body.
- The first digit is the family. 2xx means it worked, 3xx look somewhere else, 4xx the request has a problem, and 5xx the server broke.
- The codes an API sends most are 200, 201, 204, 400, 401, 403, 404, 405, 409, 422 and 500, and each one reads as a short sentence.
- Headers are notes with a name and a value. Content-Type set to application/json tells the app the body is JSON.
- Python's http.HTTPStatus names every code, such as HTTPStatus.NOT_FOUND for 404.

Before an app reads a word of the response, it reads one number. That's how a shopping app knows to show "Item not found" instead of an empty page, how a sign-up form knows the email is already taken, and how an app knows to try again later. The APIs you build will send that number, and every app that calls them will trust it, so it has to be the right one.

The example is the Greenleaf Community Garden's API, where neighbors look up plots and claim the free ones.

## A 200 that hides a problem

Every response starts with a **status code**, the three-digit number on its first line. The garden's first try at an API answered every request with 200 OK, and put any problem in the body's words. A neighbor's app asks for plot 99, which doesn't exist, and gets back (the `date` header is left out):

```http
HTTP/1.1 200 OK
server: uvicorn
content-length: 24
content-type: application/json

{"error":"no such plot"}
```

The app sees 200, which means "here it is", and tries to show plot 99's gardener: an empty card. To spot the problem, the app would have to read the words in the body, and every API words its problems differently. The status code exists so that no app has to guess.

## Status codes, read as sentences

A status code's first digit is its **family**. Read "4xx" as "four hundreds": every code from 400 to 499.

| Family | What it says | At the counter |
|---|---|---|
| 2xx | It worked | "Here you go" |
| 3xx | Look somewhere else | "That's at the next window" |
| 4xx | The request has a problem | "We don't have that" |
| 5xx | The server broke | "Sorry, the oven's down" |

These are the codes an API sends most, each read as a sentence:

| Code | Read it as |
|---|---|
| 200 OK | Here it is. |
| 201 Created | I made it, and here's the new one. |
| 204 No Content | Done, and there's nothing to send back. |
| 400 Bad Request | I can't use what you sent. |
| 401 Unauthorized | I don't know who you are: sign in first. |
| 403 Forbidden | I know who you are, and you're not allowed. |
| 404 Not Found | There's nothing at that address. |
| 405 Method Not Allowed | That address doesn't take that method. |
| 409 Conflict | That clashes with what's already here. |
| 422 Unprocessable Content | I read it, but a value in it breaks the rules. |
| 500 Internal Server Error | Something broke on my side. |

A 4xx says the caller should change the request: a different address, a missing field. A 5xx says the request may be fine and the server failed, so trying again later can work. FastAPI sends 422 when a value has the wrong type, such as `abc` where a number belongs, and you'll meet it in the next chapter.

## Choosing the code in Python

Python's standard library names every code in `http.HTTPStatus`, so your code can say `NOT_FOUND` instead of a bare 404. Here is the garden's rule for claiming a plot: the plot must exist, and it must be free:

```python
from http import HTTPStatus

GARDENERS = {1: "Rosa", 2: None, 7: "Lena"}


def claim_plot(number, gardener):
    if number not in GARDENERS:
        return HTTPStatus.NOT_FOUND
    if GARDENERS[number] is not None:
        return HTTPStatus.CONFLICT
    GARDENERS[number] = gardener
    return HTTPStatus.OK


for number in [2, 7, 9]:
    status = claim_plot(number, "Jo")
    print(number, status.value, status.phrase)
```

```text
2 200 OK
7 409 Conflict
9 404 Not Found
```

`GARDENERS` holds each plot's gardener by its number, with `None` for a free plot. Jo claims plot 2, which is free: 200. Plot 7 is Lena's, so claiming it clashes with what's there: 409. Plot 9 doesn't exist: 404. Each answer's `value` is the number and its `phrase` the words.

## Headers: notes on the envelope

A response's **headers** work like the label on a parcel: notes about what's inside, one per line, each a name, a colon and a value. Here is what FastAPI sent back when the garden's app tried `DELETE /plots` on an API that only lists plots (its `date` header is left out):

```http
HTTP/1.1 405 Method Not Allowed
server: uvicorn
allow: GET
content-length: 31
content-type: application/json

{"detail":"Method Not Allowed"}
```

- `content-type` is the **Content-Type** header: what kind of data the body is. `application/json` says "read this body as JSON". Without it, the same text could be read as a plain message.
- `content-length` is how many bytes the body has, so the app knows when it has all of it.
- `allow` lists the methods this address does take: here, only GET.
- `server` names the program that answered, here Uvicorn, which runs FastAPI apps.

Requests carry headers too, such as `Accept: application/json` ("answer in JSON, please") and, from Module 4 on, `Authorization`, which says who is asking. Header names ignore capital letters, so `content-type` and `Content-Type` are the same header. FastAPI sets `content-type: application/json` for you whenever a route returns a dictionary or a list.

## Do it: pick the status code for each situation

The garden's API keeps running into the same six situations, and each one needs its status code.

- `situation`: one of `"found"` (the plot asked for is there), `"created"` (a new plot was added), `"removed"` (a plot was deleted, with nothing to send back), `"bad input"` (the request sent something the API can't use), `"not found"` (there's no plot at that address) or `"crash"` (the API's own code broke).

**Your job:** write the function `status_for(situation)` so it returns the status code, a whole number, for each of the six situations, using the table in this lesson.

Worked through: a neighbor asks for plot 99 and there's no such plot. That's `"not found"`, "there's nothing at that address", so `status_for("not found")` returns `404`.

Practiced live on the lesson page: write the Python right there and check it.

## Check yourself

2 questions to try on the lesson page.

## So what

The status code is the one part of a response every app reads, so an API that picks the right one, and says what its body is with Content-Type, tells the truth before the app reads a single word.

## Key terms

- [Status Code](https://www.ask-codey.com/glossary/status-code)
- [Header](https://www.ask-codey.com/glossary/header-web-development)
- [Content-Type](https://www.ask-codey.com/glossary/content-type)
- [200 OK](https://www.ask-codey.com/glossary/200-ok)
- [400 Bad Request](https://www.ask-codey.com/glossary/400-bad-request)
- [500 Internal Server Error](https://www.ask-codey.com/glossary/500-internal-server-error)

## Related

- [HTTP in Plain Words: Requests and Responses](https://www.ask-codey.com/lessons/fastapi-http-requests-and-responses)
- [REST: Resources, Endpoints and Methods](https://www.ask-codey.com/lessons/fastapi-rest-resources-and-endpoints)
- [When It Isn't There: HTTPException and 404](https://www.ask-codey.com/lessons/fastapi-not-found-httpexception)

Source: https://www.ask-codey.com/lessons/fastapi-http-status-codes-and-headers
