python 34 lines · 7 steps

Custom exception handlers in FastAPI

Map a domain-specific exception to a structured HTTP error response so route handlers can fail by raising, not by formatting JSON.

Explained by highlit
FastAPI Intermediate exception handling error responses separation of concerns domain modeling
1from fastapi import FastAPI, Request, status
2from fastapi.responses import JSONResponse
3 
4app = FastAPI()
5 
6 
7class InsufficientFundsError(Exception):
8 def __init__(self, account_id: str, balance: float, requested: float):
9 self.account_id = account_id
10 self.balance = balance
11 self.requested = requested
12 
13 
14@app.exception_handler(InsufficientFundsError)
15async def insufficient_funds_handler(request: Request, exc: InsufficientFundsError):
16 return JSONResponse(
17 status_code=status.HTTP_402_PAYMENT_REQUIRED,
18 content={
19 "error": "insufficient_funds",
20 "message": f"Account {exc.account_id} cannot withdraw {exc.requested:.2f}.",
21 "available_balance": exc.balance,
22 "shortfall": round(exc.requested - exc.balance, 2),
23 },
24 headers={"X-Error-Code": "INSUFFICIENT_FUNDS"},
25 )
26 
27 
28@app.post("/accounts/{account_id}/withdraw")
29async def withdraw(account_id: str, amount: float):
30 account = await accounts.get(account_id)
31 if amount > account.balance:
32 raise InsufficientFundsError(account_id, account.balance, amount)
33 await account.debit(amount)
34 return {"account_id": account_id, "balance": account.balance - amount}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Centralizing error formatting in a handler keeps route logic focused on the happy path.
  2. 2A custom exception can carry rich context that the handler turns into a meaningful response.
  3. 3Mapping domain failures to specific status codes makes an API's errors predictable for clients.

Related explainers

python 
from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, status
from pydantic import BaseModel, EmailStr
from sqlalchemy.orm import Session
 

Building a signup endpoint in FastAPI

dependency-injection request-validation background-tasks
Intermediate 8 steps
python 
from django import forms
from django.utils import timezone
 
from .models import Reservation

Multi-field validation in a Django ModelForm

form validation cross-field validation modelform
Intermediate 7 steps
python 
from django import template
from django.urls import reverse, NoReverseMatch
from django.utils.html import format_html
 

Active nav-link template tags in Django

template tags url routing active state
Intermediate 7 steps
python 
from functools import wraps
import asyncio
 
from fastapi import APIRouter, FastAPI, Request

Per-route request timeouts in FastAPI

decorators async timeouts
Intermediate 6 steps
python 
import os
from pathlib import Path
 
BASE_DIR = Path(__file__).resolve().parent.parent.parent

How a Django settings module is wired

configuration environment-variables middleware
Intermediate 8 steps
ruby 
class Order < ApplicationRecord
  include AASM
 
  belongs_to :warehouse

Modeling an order lifecycle with AASM in Rails

state machine guards callbacks
Intermediate 10 steps

Share this explainer

Here's the card — post it anywhere.

Custom exception handlers in FastAPI — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code