Custom request validation in FastAPI - Deep Dive

Overview - Custom request validation

What is it?

Custom request validation in FastAPI means checking the data sent by users to your app in ways that go beyond the automatic checks FastAPI does. It lets you write your own rules to make sure the data fits exactly what your app needs. This helps catch mistakes or bad data early, before your app tries to use it. Custom validation can be done by writing special functions or classes that FastAPI calls when it gets data.

Why it matters

Without custom validation, your app might accept wrong or harmful data, causing errors or security problems later. Automatic checks cover common cases but can't handle all specific rules your app needs. Custom validation ensures data is correct and safe, improving user experience and app reliability. It saves time by catching problems early and helps your app behave exactly as intended.

Where it fits

Before learning custom validation, you should understand FastAPI basics, including how to define request models with Pydantic and how automatic validation works. After mastering custom validation, you can explore advanced topics like dependency injection, security, and error handling to build robust APIs.

Mental Model

Core Idea

Custom request validation is writing your own rules to check user data before your app uses it, ensuring it fits your exact needs.

Think of it like...

It's like a security guard at a club who not only checks IDs but also verifies dress code and behavior before letting people in.

┌─────────────────────────────┐
│      Incoming Request Data  │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│  Automatic Validation (FastAPI) │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│  Custom Validation Functions │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│   Validated & Clean Data     │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding FastAPI automatic validation

Concept: FastAPI uses Pydantic models to automatically check incoming request data against expected types and formats.

When you define a request body model with Pydantic, FastAPI checks that the data matches the model's fields and types. For example, if a field expects an integer but gets a string, FastAPI returns an error before your code runs.

Result

Requests with wrong data types or missing required fields are rejected automatically with clear error messages.

Understanding automatic validation is key because custom validation builds on top of this foundation to handle more specific rules.

2

Foundation

Basics of Pydantic validators

Concept: Pydantic models support custom validation methods to check or transform data during model creation.

You can add methods decorated with @validator inside your Pydantic model to run extra checks on fields. These methods receive the field value and can raise errors if the value is invalid or modify it before saving.

Result

You get more control over individual fields, like checking a string length or ensuring a number is positive.

Knowing Pydantic validators lets you customize validation close to the data structure, making your checks reusable and clean.

3

Intermediate

Using root validators for cross-field checks

🤔Before reading on: do you think you can validate multiple fields together using regular field validators? Commit to yes or no.

Concept: Root validators allow checking multiple fields at once, useful when validation depends on the relationship between fields.

By adding a method decorated with @root_validator(pre=False), you get the whole model's data at once. You can then write logic that compares fields or enforces rules involving several fields together.

Result

You can enforce rules like 'field A must be greater than field B' or 'if field C is set, field D must be present'.

Understanding root validators unlocks complex validation scenarios that single-field checks can't handle.

4

Intermediate

Raising custom errors with HTTPException

🤔Before reading on: do you think Pydantic validation errors automatically return HTTP status codes? Commit to yes or no.

Concept: You can raise FastAPI's HTTPException inside validation to return specific HTTP error codes and messages.

Inside your custom validation logic, you can import HTTPException from fastapi and raise it with a status code and detail message. This lets you control the API response when validation fails beyond Pydantic's default errors.

Result

Clients receive clear HTTP error responses tailored to your validation logic, improving API usability.

Knowing how to raise HTTPException during validation helps you provide better feedback and handle errors gracefully.

5

Advanced

Creating reusable custom validators

🤔Before reading on: do you think you must write validation logic inside each Pydantic model separately? Commit to yes or no.

Concept: You can write standalone functions or classes to reuse validation logic across multiple models or endpoints.

Define functions that accept values and raise errors if invalid. Then use Pydantic's validator decorator with 'allow_reuse=True' to apply these functions in multiple models. Alternatively, create custom types with their own validation logic.

Result

Validation code is DRY (Don't Repeat Yourself), easier to maintain, and consistent across your app.

Understanding reusable validators improves code quality and reduces bugs in large projects.

6

Expert

Advanced validation with dependencies and middleware

🤔Before reading on: do you think all validation must happen inside Pydantic models? Commit to yes or no.

Concept: FastAPI allows validation outside models using dependencies or middleware for complex or global checks.

You can write dependency functions that run before your endpoint logic to validate headers, tokens, or complex request parts. Middleware can inspect and validate requests globally. This separates concerns and handles validation that Pydantic models can't cover, like authentication or rate limiting.

Result

Your app gains flexible, layered validation strategies that improve security and maintainability.

Knowing how to combine model validation with dependencies and middleware lets you build robust, scalable APIs.

Under the Hood

FastAPI uses Pydantic to parse and validate incoming JSON data by creating model instances. Pydantic runs type checks and calls any custom validators defined on the model. If validation fails, Pydantic raises ValidationError, which FastAPI catches and converts into HTTP 422 responses. Custom validators are just Python functions called during model creation, allowing arbitrary logic. Dependencies and middleware run before endpoint code, letting you validate other request parts or apply global rules.

Why designed this way?

FastAPI was designed to combine Python's type hints with Pydantic's powerful validation to provide automatic, clear, and fast request validation. Custom validation was added to let developers handle cases beyond simple type checks without losing the benefits of automatic validation. Using dependencies and middleware for validation fits FastAPI's modular design, separating concerns and improving code reuse and testability.

┌───────────────┐
│ HTTP Request  │
└──────┬────────┘
       │ JSON body
       ▼
┌───────────────┐
│ Pydantic Model│
│  Parsing &    │
│  Validation   │
└──────┬────────┘
       │ Calls custom validators
       ▼
┌───────────────┐
│ Validation    │
│  Success or   │
│  ValidationError ├─────────────┐
└──────┬────────┘             │
       │                      │
       ▼                      ▼
┌───────────────┐       ┌───────────────┐
│ Endpoint Code │       │ FastAPI Error │
│  Runs with    │       │ Handler sends │
│  Valid Data   │       │ HTTP 422      │
└───────────────┘       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think Pydantic validators run after your endpoint code? Commit to yes or no.

Common Belief: Validators run after the endpoint function starts, so you can catch errors inside your code.

Reality: Validators run before the endpoint function is called, during request parsing. If validation fails, the endpoint code never runs.

Why it matters: Expecting validation inside endpoint code can cause confusion and bugs because invalid data never reaches your logic.

Quick: Do you think raising ValueError inside a validator returns a 500 server error? Commit to yes or no.

Common Belief: Raising ValueError causes a server crash or 500 error.

Reality: Pydantic catches ValueError and converts it into a validation error, which FastAPI returns as a 422 client error.

Why it matters: Misunderstanding this can lead to improper error handling and unclear API responses.

Quick: Do you think all validation must be inside Pydantic models? Commit to yes or no.

Common Belief: Validation only belongs in Pydantic models; dependencies or middleware are not for validation.

Reality: Dependencies and middleware are powerful places for validation, especially for headers, authentication, or global rules.

Why it matters: Ignoring these options limits your ability to handle complex validation scenarios and maintain clean code.

Quick: Do you think custom validators can modify other fields besides the one they validate? Commit to yes or no.

Common Belief: Field validators can change any field's value in the model.

Reality: Field validators only receive and modify their own field; cross-field changes require root validators.

Why it matters: Trying to modify other fields in field validators leads to bugs and unexpected behavior.

Expert Zone

1

Custom validators run in the order they are defined, which can affect validation logic when multiple validators exist on the same field.

2

Root validators can be run before or after field validators by setting pre=True or False, changing when cross-field checks happen.

3

Using dependencies for validation allows asynchronous checks, like database lookups, which Pydantic validators cannot do because they are synchronous.

When NOT to use

Avoid putting complex business logic or asynchronous validation inside Pydantic models; instead, use FastAPI dependencies or middleware. For very simple data checks, rely on automatic validation to keep code clean. If you need global request validation like authentication or rate limiting, use middleware rather than model validators.

Production Patterns

In production, teams often combine Pydantic validators for data shape and format with dependencies for security and context-aware validation. Reusable validator functions and custom types enforce consistency across many endpoints. Middleware handles cross-cutting concerns like logging and global validation. Validation errors are customized with HTTPException to provide clear API feedback.

Connections

Type Systems in Programming Languages

Custom validation builds on static type checking by adding dynamic, runtime checks.

Understanding how type systems enforce rules at compile time helps appreciate why runtime validation is still needed for user input, which is unpredictable.

Middleware in Web Servers

Validation via middleware is a pattern shared across web frameworks to handle cross-cutting concerns.

Knowing middleware concepts from other frameworks helps understand how FastAPI can validate requests globally, not just per endpoint.

Quality Control in Manufacturing

Custom validation is like quality control checks ensuring each product meets standards before shipping.

Seeing validation as a quality gate clarifies why catching errors early prevents bigger problems downstream.

Common Pitfalls

#1 Trying to perform asynchronous validation inside Pydantic validators.

Wrong approach:

from pydantic import BaseModel, validator

class User(BaseModel):
email: str

@validator('email')
async def check_email(cls, v):
# pretend async check
if not await is_email_unique(v):
raise ValueError('Email already used')
return v

Correct approach:

from pydantic import BaseModel
from fastapi import Depends, HTTPException

class User(BaseModel):
email: str

async def validate_email_unique(email: str):
if not await is_email_unique(email):
raise HTTPException(status_code=400, detail='Email already used')
return email

@app.post('/users')
async def create_user(user: User, email=Depends(validate_email_unique)):
# proceed with user creation
pass

Root cause:

Pydantic validators are synchronous and cannot await async calls; asynchronous validation must be done outside models using FastAPI dependencies.

#2 Raising generic exceptions inside validators instead of Pydantic errors or HTTPException.

Wrong approach:

from pydantic import BaseModel, validator

class Item(BaseModel):
price: float

@validator('price')
def check_price(cls, v):
if v < 0:
raise Exception('Price must be positive')
return v

Correct approach:

from pydantic import BaseModel, validator

class Item(BaseModel):
price: float

@validator('price')
def check_price(cls, v):
if v < 0:
raise ValueError('Price must be positive')
return v

Root cause:

Raising generic exceptions can cause server errors; Pydantic expects ValueError or TypeError to convert to validation errors properly.

#3 Trying to modify other fields inside a field validator.

Wrong approach:

from pydantic import BaseModel, validator

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

@validator('name')
def fix_price_if_name(cls, v, values):
if v == 'Free':
values['price'] = 0 # This does not work
return v

Correct approach:

from pydantic import BaseModel, root_validator

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

@root_validator
def fix_price_if_name(cls, values):
if values.get('name') == 'Free':
values['price'] = 0
return values

Root cause:

Field validators only receive their own field value; cross-field changes require root validators that access the whole model.

Key Takeaways

FastAPI uses Pydantic models to automatically validate request data, but custom validation lets you enforce rules beyond basic type checks.

Pydantic validators and root validators provide flexible ways to check individual fields or multiple fields together during model creation.

For asynchronous or complex validation, use FastAPI dependencies or middleware instead of Pydantic validators.

Raising the right exceptions during validation ensures your API returns clear, user-friendly error messages.

Combining automatic, custom, and global validation strategies builds robust, maintainable, and secure APIs.