FastAPI 4xx Error Handling with HTTPException

Exception Nostalgia!! Coded in Java for several years and moved to Python recently, nevertheless the core concepts remain the same be it the classes, functions or exception handling :) 🚀 FastAPI Insight: Why Your 4xx Errors Still Show “detail” (and how to fix it cleanly) While working with FastAPI, I came across a subtle but important behavior in error handling. 🔍 The Situation You raise an exception like this: raise HTTPException( status_code=422, detail={ "error_code": "VALIDATION_ERROR", "message": "Something went wrong" } ) But the response always comes back as: { "detail": { "error_code": "...", "message": "..." } } 🤔 Even though you passed a custom structure, FastAPI wraps everything inside "detail". 🧠 Key Insight HTTPException → controls the status code FastAPI → always wraps response inside detail You cannot change this behavior directly ⚠️ Common Mistake Catching all exceptions like this: except Exception as e: This also catches HTTPException ❌ Result → Your intended 4xx/5xx error may get converted into a 200 response (bad API design) ✅ Correct Pattern except HTTPException: raise # preserve original status code 💡 The Real Solution If you want a clean, consistent API response like: { "status": "error", "error": { ... } } 👉 You need to override FastAPI’s default behavior: @app.exception_handler(HTTPException) async def custom_handler(request, exc): return JSONResponse( status_code=exc.status_code, content={ "status": "error", "error": exc.detail } ) 🎯 Final Takeaway ✔️ Use HTTPException for proper HTTP semantics ✔️ Always re-raise it inside except blocks ✔️ Use a custom exception handler for consistent API contracts This small tweak can make your API: Cleaner More predictable Easier to integrate with frontend systems #FastAPI #BackendDevelopment #Python #APIDesign #SoftwareEngineering #CleanCode #Microservices

To view or add a comment, sign in

Explore content categories