FastAPI Pydantic V2 Rust Engine, Validation & Error Handling

Data validation and serialization in FastAPI are powered by Pydantic V2. In Pydantic V2, the core validation engine was entirely rewritten from Python into Rust (pydantic-core), delivering a 5x to 20x performance improvement. Understanding Pydantic V2’s execution model, custom validation rules (@field_validator, @model_validator), and custom exception handlers is essential for building resilient APIs.

This chapter details the Pydantic V2 Rust architecture, validation flow, error formatting, and custom exception handler registration.

1. Pydantic V2 Rust Core Architecture (pydantic-core)

In Pydantic V1, validation was executed in Python using dynamic reflection and type checks. Pydantic V2 separates schema definition from validation execution:

• Python Layer (pydantic): Defines models, type annotations, and validation decorators.
• Rust Core (pydantic-core): A compiled C-extension written in Rust. When a Pydantic model is defined in Python, pydantic-core compiles an immutable validation tree in C/Rust memory.

Pydantic V2 Rust Validation Pipeline:

[ Incoming Raw JSON Bytes ]
             |
             v
[ ujson / C-JSON Parser ]
             |
             v
[ pydantic-core Rust Validation Engine ]  <-- 5x-20x faster C/Rust execution!
     ├─ Check types & bounds in Rust memory
     ├─ Execute C-level coercion rules
     └─ Invoke Python Custom Validators (@field_validator)
             |
             v
[ Validated Pydantic Model Instance (Python Heap) ]

2. Validation Decorators: @field_validator & @model_validator

Pydantic V2 provides two primary validation decorators:

1. @field_validator (Field-Level):

Validates or mutates a single field before or after standard Pydantic validation.

from pydantic import BaseModel, field_validator

class UserCreate(BaseModel):
    username: str

    @field_validator('username')
    @classmethod
    def username_must_be_alphanumeric(cls, v: str) -> str:
        if not v.isalnum():
            raise ValueError('Username must be alphanumeric')
        return v.lower()

2. @model_validator(mode='after') (Cross-Field):

Validates relationships between multiple fields after field-level validation completes.

from pydantic import BaseModel, model_validator

class PasswordChange(BaseModel):
    password: str
    confirm_password: str

    @model_validator(mode='after')
    def check_passwords_match(self) -> 'PasswordChange':
        if self.password != self.confirm_password:
            raise ValueError('Passwords do not match')
        return self

3. Global Exception Handling (RequestValidationError)

When incoming request data fails validation, FastAPI automatically catches pydantic.ValidationError or fastapi.exceptions.RequestValidationError and returns a standard HTTP 422 Unprocessable Entity response.

You can override this global error response using @app.exception_handler:

from fastapi import FastAPI, Request, status
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def custom_validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={
            "error_code": "INVALID_PAYLOAD",
            "message": "Input validation failed",
            "details": exc.errors()
        },
    )

4. Production Trade-offs & Model Re-use

• Model Separation: Do not use database ORM models (SQLAlchemy/SQLModel) directly as request body parameters. Maintain strict separation between Request DTOs (UserCreate), Response DTOs (UserResponse), and Database ORM Entities (UserModel).
• mode='json' vs mode='python': In Pydantic V2, model_validate_json() parses raw JSON strings directly inside Rust, bypassing Python string allocation overhead.