How to Handle 500 Internal Server Errors in FastAPI

In FastAPI, you handle 500 Internal Server Errors by creating a custom exception handler for HTTPException or catching Exception globally. Use @app.exception_handler(Exception) to define how your app responds when unexpected errors occur, preventing raw 500 errors from reaching users.

Why This Happens

A 500 Internal Server Error happens when your FastAPI app encounters an unexpected problem it doesn't know how to handle. This could be a bug, a missing resource, or a failure in your code logic. Without special handling, FastAPI returns a generic 500 error response to the client.

python

from fastapi import FastAPI

app = FastAPI()

@app.get("/cause-error")
def cause_error():
    # This will cause a ZeroDivisionError
    result = 1 / 0
    return {"result": result}

Output

Internal Server Error (500) with default FastAPI error page

The Fix

To fix this, add a global exception handler that catches unexpected errors and returns a friendly message or custom response. This prevents raw 500 errors and helps you log or manage errors gracefully.

python

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    return JSONResponse(
        status_code=500,
        content={"message": "Oops! Something went wrong. Please try again later."}
    )

@app.get("/cause-error")
def cause_error():
    result = 1 / 0
    return {"result": result}

Output

{"message": "Oops! Something went wrong. Please try again later."}

Prevention

To avoid unexpected 500 errors, write clean code with proper error checks and validations. Use try-except blocks where errors are likely. Always add global exception handlers to catch unhandled errors and log them for debugging. Use tools like pytest for testing and logging to track issues early.

Related Errors

Other common errors include 404 Not Found when a resource is missing, and 422 Unprocessable Entity when request data is invalid. Handle these with specific exception handlers like HTTPException for 404 and Pydantic validation errors for 422 to improve user feedback.

Key Takeaways

Use @app.exception_handler(Exception) to catch and handle all unexpected errors globally.

Return user-friendly messages instead of raw 500 error pages to improve user experience.

Write clean code with validations and try-except blocks to prevent errors.

Log errors inside exception handlers to help with debugging and monitoring.

Handle other HTTP errors like 404 and 422 with specific exception handlers.