Welcome to Day 10 of the FastAPI Zero to Hero 🚀 series!
Today, we dive into something every developer faces — Errors! But instead of fearing them, let's learn how to handle them like a pro in FastAPI. 💪
🎯 Why Exception Handling Matters
Think about this:
Online, you're placing a food order. The pincode you entered is not valid.
The application should gently notify you that the pincode is invalid or crash. Please give it another go."_?
It is normal to make mistakes in the real world. Effective APIs communicate what went wrong; they don't break.
Because of this, exception handling is essential for: - A pristine user experience
Improved debugging; safe and dependable APIs
⚙️ What You'll Learn Today
- Using
HTTPException(built-in FastAPI tool) - Creating global exception handlers
- Defining your own custom exceptions like a boss 💼
💥 1. Raise an HTTPException
When you want to throw a standard API error, use HTTPException.
from fastapi import FastAPI, HTTPException
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id: int):
if item_id == 0:
raise HTTPException(status_code=404, detail="Item not found")
return {"item_id": item_id}
🌐 2. Global Exception Handler
Want to catch all ValueErrors and return a clean message instead of a scary stack trace?
Let’s register a global exception handler in FastAPI 👇
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
app = FastAPI()
# Global exception handler for ValueError
@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
return JSONResponse(
status_code=400,
content={"detail": str(exc)}
)
✅ What comes next?
Instead of displaying the raw traceback, FastAPI will automatically utilise this handler whenever a ValueError is raised in your application and return a tidy JSON error.
🧑🎨 3. Create Your Own Custom Exceptions
Built-in exceptions such as HTTPException and ValueError are insufficient in certain situations.
What if you require a bespoke PaymentFailedError for your business logic?
You can create your own exception classes using FastAPI and manage them effectively with unique replies and logic.
🧱 Step 1: Define Your Custom Exception
class PaymentFailedError(Exception):
def __init__(self, reason: str):
self.reason = reason
This is just a normal Python exception. You can extend it with more attributes if needed.
🔧 Step 2: Register a Custom Exception Handler
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
app = FastAPI()
@app.exception_handler(PaymentFailedError)
async def payment_failed_handler(request: Request, exc: PaymentFailedError):
return JSONResponse(
status_code=402,
content={"detail": f"Payment failed: {exc.reason}"}
)
Here, whenever PaymentFailedError is raised, FastAPI will use this handler to return a structured JSON response.
🚀 Step 3: Use Your Custom Exception in a Route
@app.get("/pay")
def pay():
# Simulate a failed payment scenario
raise PaymentFailedError("Card declined by bank")
✅ Full FastAPI Code Example with Exception Handling
This example covers:
- 🔹 Raising built-in
HTTPException - 🌐 Global handler for
ValueError - 🧑🎨 Custom exception:
PaymentFailedError
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse
app = FastAPI()
# -----------------------------------
# 1. Raise HTTPException Example
# -----------------------------------
@app.get("/items/{item_id}")
def read_item(item_id: int):
if item_id == 0:
raise HTTPException(status_code=404, detail="Item not found")
return {"item_id": item_id}
# -------------------------------------------
# 2. Global Exception Handler for ValueError
# -------------------------------------------
@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
return JSONResponse(
status_code=400,
content={"detail": f"ValueError: {str(exc)}"},
)
@app.get("/divide")
def divide_numbers(a: int = 10, b: int = 0):
if b == 0:
raise ValueError("Division by zero is not allowed.")
return {"result": a / b}
# -----------------------------------
# 3. Custom Exception: PaymentFailed
# -----------------------------------
class PaymentFailedError(Exception):
def __init__(self, reason: str):
self.reason = reason
@app.exception_handler(PaymentFailedError)
async def payment_failed_handler(request: Request, exc: PaymentFailedError):
return JSONResponse(
status_code=402,
content={"detail": f"Payment failed: {exc.reason}"},
)
@app.get("/pay")
def pay():
raise PaymentFailedError("Card declined by bank")
▶️ Run the FastAPI App
Use uvicorn to run your FastAPI server locally:
uvicorn excpetions:app --host 0.0.0.0 --reload --port 9000
🔹 /items/0 → HTTPException
URL to hit:
http://localhost:9000/items/0
🌐 /divide?a=10&b=0 → Global ValueError Handler
URL to hit:
http://localhost:9000/divide?a=10&b=0
🧑🎨 /pay → Custom PaymentFailedError
URL to hit:
http://localhost:9000/pay
🧾 Wrap-Up: Why Exception Handling Matters
Exception handling isn't just a developer convenience — it's a critical part of building reliable APIs.
In this FastAPI example, you learned how to:
✅ Raise built-in exceptions like HTTPException for standard error cases
🌐 Register global handlers (e.g., for ValueError) to keep your code DRY and consistent
🧑🎨 Create custom exceptions like PaymentFailedError to match real-world business scenarios
🔍 Real-World Relevance
Here’s how this maps to real-world applications:
-
HTTPException: Missing resources like/user/0,/product/9999→ 404 Not Found -
ValueError: Invalid input like dividing by zero or parsing errors → 400 Bad Request -
Custom Exceptions: Payment failures, quota limits, licensing errors → Business-specific error codes like 402 Payment Required, 429 Too Many Requests, etc.
🚀 Pro Tip
With well-structured exception handling:
- Your API becomes more developer-friendly
- Your errors are easier to log, debug, and trace
- You leave room to plug in monitoring tools, custom logging, or even alerting systems
🙏 Credits
Huge thanks to the FastAPI Official Documentation by Sebastián Ramírez (@tiangolo) — the best place to learn and explore everything about FastAPI.
👨💻 About Me
Hey there! I’m Utkarsh Rastogi, an AWS Community Builder and passionate cloud-native enthusiast who loves building scalable backend systems and sharing knowledge with the community.
🔗 Connect with me: Utkarsh Rastogi
💬 Share Your Thoughts – I'd Love Your Feedback!
If you enjoyed today's post or learned something new, I'd truly appreciate it if you leave a comment or share your thoughts 👇
Your feedback, questions, or even a quick “🔥 Loved this!” keeps me motivated to continue this journey and share more in the upcoming #FastAPIDaily posts.
✅ What did you find most helpful?
✅ Anything you'd like explained in the next part?
✅ Suggestions for improvement? I’m all ears! 🙌
Let’s grow and learn together — one FastAPI day at a time 🚀
Top comments (0)