How to Handle Validation Errors in FastAPI Correctly

In FastAPI, validation errors automatically raise a RequestValidationError. You can handle these errors by creating a custom exception handler using @app.exception_handler(RequestValidationError) to return friendly error messages or custom responses.

Why This Happens

FastAPI uses Pydantic to validate incoming request data. When the data does not match the expected format or types, FastAPI raises a RequestValidationError automatically. If you don't handle this error, FastAPI returns a default JSON error response with details.

python

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")
async def create_item(item: Item):
    return item

Output

{
  "detail": [
    {
      "loc": ["body", "price"],
      "msg": "value is not a valid float",
      "type": "type_error.float"
    }
  ]
}

The Fix

To customize validation error handling, add an exception handler for RequestValidationError. This lets you control the error response format or message, making it clearer for API users.

python

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={"error": "Validation failed", "details": exc.errors()}
    )

@app.post("/items/")
async def create_item(item: Item):
    return item

Output

{
  "error": "Validation failed",
  "details": [
    {
      "loc": ["body", "price"],
      "msg": "value is not a valid float",
      "type": "type_error.float"
    }
  ]
}

Prevention

Always define clear Pydantic models for your request data to ensure validation is automatic and consistent. Use custom exception handlers to provide user-friendly error messages. Test your API inputs to catch validation issues early. Consider using tools like pytest with FastAPI's TestClient to automate validation tests.

Related Errors

Other common errors include ValidationError from Pydantic when creating models manually, and HTTPException for general HTTP errors. Handling these with custom exception handlers improves API clarity and user experience.

Key Takeaways

FastAPI raises RequestValidationError automatically on invalid input data.

Use @app.exception_handler(RequestValidationError) to customize validation error responses.

Define clear Pydantic models to enable automatic validation.

Test API inputs to catch validation errors early.

Custom error handlers improve API usability and clarity.