What

Three handlers each re-derived the not-found → 404 policy, via two different mechanisms:

• get_deck / get_card: get_one_or_none(...) then if not instance: raise HTTPException(404, ...)
• update_deck: try: ... except NotFoundError: raise HTTPException(404, ...)

This consolidates that policy into one seam: a single NotFoundError → 404 handler registered in build_app, mirroring the existing DuplicateKeyError handler.

Ports modern-python/litestar-sqlalchemy-template#27 to this template, adapted to FastAPI idioms (JSONResponse handler, add_exception_handler, typing.cast responses preserved).

Changes

• app/exceptions.py — new not_found_error_handler returning 404 {"detail": "Not found"}.
• app/application.py — register NotFoundError: exceptions.not_found_error_handler.
• app/repositories.py — fetch_with_cards tightens to -> models.Deck, using get_one (raises on miss) instead of get_one_or_none.
• app/api/decks.py — get_deck / update_deck / get_card drop all 404 code; get_card uses get_one. Removed now-unused imports (NotFoundError, starlette status, HTTPException usage).

No handler mentions 404 any more — the not-found decision lives where the data access happens, mapped to a response in one place.

Decisions

• Seam = advanced-alchemy NotFoundError (the signal the repository already emits; matches the DuplicateKeyError convention).
• Reads use the raising variant; the raise is pushed behind fetch_with_cards.
• 404 body is generic {"detail": "Not found"} — advanced-alchemy's NotFoundError.detail is empty and no test asserts the message (the existing 404 tests assert status code only).

Verification

• just test → 19 passed, 100% coverage
• ruff format --check / ruff check --no-fix / ty check clean

🤖 Generated with Claude Code