# When It Isn't There: HTTPException and 404

A FastAPI route answers 404 for an item that isn't there by raising HTTPException with a status code and a detail message, which stops the function at once and sends {"detail": ...}, and a route that creates something sets status_code=201 on its decorator.

Apprentice · FastAPI · REST API · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Answer 404 for an item that isn't there by raising HTTPException with a detail message, and explain why it's raised and not returned
- Choose a route's success status code with status_code= on its decorator, such as 201 for a route that creates something

## Key takeaways

- A route that finds nothing must still say so with its status code. An answer of 200 with null or an error message tells the app that everything went fine.
- raise HTTPException(status_code=404, detail="...") stops the function at once and answers 404 with the body {"detail": "..."}.
- HTTPException has to be raised, not returned. Returned, it's sent as an ordinary 200 answer that happens to contain the words 404.
- Because raising stops everything, a helper function such as find_game can raise the 404 for every route that uses it.
- A route answers 200 unless you choose otherwise. status_code=201 on the decorator says that the route created something.

Ask an API for something that doesn't exist, an order that was never placed or a user who deleted their account, and the app on the other end needs to know, so it can show "not found" instead of a blank screen. The status code is how an API says it, and *Status Codes and Headers* read them as sentences: 404 means "there's nothing at that address". This lesson shows how a FastAPI route sends one.

The example is the Rolling Dice café's API from *Path Parameters and Their Types*, where `/games/9` still answers 200 with `null`.

## A 200 that isn't fine

The café's shelf has three games, so there's no game 9. The route's loop finds nothing, and the function ends without returning a game. The staff app gets status 200, which says "here it is", and a body of `null`, and shows an empty card.

A first try is to return a message instead:

```python
@app.get("/games/{game_id}")
def get_game(game_id: int):
    for game in GAMES:
        if game["id"] == game_id:
            return game
    return {"error": f"There's no game {game_id}."}
```

`/games/9` now answers 200 with this body:

```json
{"error":"There's no game 9."}
```

A person can read it, but the app checks the status code first, and 200 still says "here it is". The app would try to show a game whose title is missing. The message is right; the status code is wrong.

## raise HTTPException

FastAPI's `HTTPException` carries a status code and a message. You **raise** it, the way Python raises a `ValueError` (*Handling Errors with try and except* shows raising and catching): the function stops on that line, and FastAPI sends an answer with that status code.

```python
from fastapi import FastAPI, HTTPException

app = FastAPI()

GAMES = [
    {"id": 1, "title": "Harbor Lights", "min_players": 2, "max_players": 4, "minutes": 45, "available": True},
    {"id": 2, "title": "Moon Mice", "min_players": 3, "max_players": 6, "minutes": 20, "available": False},
    {"id": 3, "title": "Tile Town", "min_players": 1, "max_players": 2, "minutes": 30, "available": True},
]


@app.get("/games/{game_id}")
def get_game(game_id: int):
    for game in GAMES:
        if game["id"] == game_id:
            return game
    raise HTTPException(status_code=404, detail=f"There's no game {game_id}.")
```

`/games/9` answers 404 Not Found, and `detail` becomes the body:

```json
{"detail":"There's no game 9."}
```

`/games/2` still answers 200 with Moon Mice: the `raise` line runs only when the loop finishes without returning. A request for an address the app has no route for at all, such as `/snacks`, gets FastAPI's own 404, with the body `{"detail":"Not Found"}`.

## Raised, not returned

`HTTPException` is an object like any other, so a route can return it by mistake:

```python
    return HTTPException(status_code=404, detail=f"There's no game {game_id}.")
```

FastAPI then treats it as data to send. `/games/9` answers 200 OK with this body:

```json
{"status_code":404,"detail":"There's no game 9.","headers":null}
```

The number 404 is in there, but only as text in the body; the real status code is 200. Only a raised `HTTPException` changes the status code.

Raising has a second advantage: it stops everything, even from inside another function. The café's routes all need "find the game, or answer 404", so one helper can do it for all of them:

```python
def find_game(game_id):
    for game in GAMES:
        if game["id"] == game_id:
            return game
    raise HTTPException(status_code=404, detail=f"There's no game {game_id}.")


@app.get("/games/{game_id}")
def get_game(game_id: int):
    return find_game(game_id)
```

When `find_game` raises, `get_game` stops too, and the 404 goes out. Each route that uses the helper stays one line long.

## 201: choosing the success code

Every route answers 200 OK when it succeeds, unless you choose another code. The café counts how often each game is played: `POST /games/2/plays` records a play of Moon Mice. That request creates something new, and 201 Created says so. Set it with `status_code=` on the decorator:

```python
PLAYS = []


@app.post("/games/{game_id}/plays", status_code=201)
def record_play(game_id: int):
    game = find_game(game_id)
    play = {"id": len(PLAYS) + 1, "game_id": game_id, "title": game["title"]}
    PLAYS.append(play)
    return play
```

`@app.post` (read "at app dot post") ties the function to POST requests. The first `POST /games/2/plays` answers 201 Created:

```json
{"id":1,"game_id":2,"title":"Moon Mice"}
```

`POST /games/9/plays` answers 404 with `{"detail":"There's no game 9."}`: `find_game` raised before anything was recorded, and the 404 replaced the 201. You'll try POST routes on the docs page in the next lesson, *Taking JSON In: Your First Request Body*.

## Check yourself

2 questions to try on the lesson page.

## So what

The status code is the first thing an app reads, so a route that raises a 404 when something's missing and sends 201 when it creates something tells the app the truth before it reads a word of the body.

## Key terms

- [HTTPException](https://www.ask-codey.com/glossary/httpexception)
- [404 Not Found](https://www.ask-codey.com/glossary/404-not-found)
- [201 Created](https://www.ask-codey.com/glossary/201-created)
- [Status Code in FastAPI](https://www.ask-codey.com/glossary/status-code-in-fastapi)

## Related

- [Path Parameters and Their Types](https://www.ask-codey.com/lessons/fastapi-path-parameters)
- [Taking JSON In: Your First Request Body](https://www.ask-codey.com/lessons/fastapi-first-request-body)
- [Status Codes and Headers](https://www.ask-codey.com/lessons/fastapi-http-status-codes-and-headers)

Source: https://www.ask-codey.com/lessons/fastapi-not-found-httpexception
