Validation Errors

Learn the fundamentals of validation errors in FastAPI.

🎯 Core Concept

FastAPI automatically validates request data using Pydantic models. When data doesn't match the expected format, FastAPI returns a 422 Unprocessable Entity response with detailed validation errors. Understanding these errors helps clients debug API usage issues.

📖 What You'll Learn

In this section, you'll understand:

• How FastAPI validates request data

• How it applies to real-world API development

• Understanding validation error responses

• Common patterns and best practices

💡 Understanding Validation Errors

When you define a Pydantic model, FastAPI automatically validates incoming data:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

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

Invalid request (price is string instead of float):

{
  "name": "Widget",
  "price": "not-a-number",
  "quantity": 5
}

FastAPI response (automatic validation error):

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

🔍 Validation Error Structure

# Invalid: Missing required field
{
  "detail": [
    {
      "loc": ["body", "price"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

# Invalid: Type mismatch
{
  "detail": [
    {
      "loc": ["body", "quantity"],
      "msg": "value is not a valid integer",
      "type": "value_error.integer"
    }
  ]
}

# Invalid: Multiple errors
{
  "detail": [
    {"loc": ["body", "name"], "msg": "field required", "type": "value_error.missing"},
    {"loc": ["body", "price"], "msg": "value is not a valid float", "type": "value_error.float"}
  ]
}

💼 Custom Validation Logic

from pydantic import BaseModel, field_validator

class Product(BaseModel):
    name: str
    price: float
    discount: float = 0

    @field_validator('price')
    def price_must_be_positive(cls, v):
        if v <= 0:
            raise ValueError('Price must be greater than 0')
        return v

    @field_validator('discount')
    def discount_must_be_valid(cls, v, values):
        if v > values.get('price', 0):
            raise ValueError('Discount cannot exceed price')
        return v

How it applies to real-world API development

Validation errors are critical for:

• **Form submissions**: Ensure all required fields are provided

• **E-commerce**: Validate prices, quantities, and payment details

• **User registration**: Ensure emails, passwords meet requirements

• **API integrations**: Validate webhook payloads from third parties

Example - User registration with custom validation:

from pydantic import BaseModel, EmailStr, field_validator

class UserCreate(BaseModel):
    username: str
    email: EmailStr
    password: str
    age: int

    @field_validator('username')
    def username_alphanumeric(cls, v):
        if not v.isalnum():
            raise ValueError('Username must be alphanumeric')
        if len(v) < 3:
            raise ValueError('Username must be at least 3 characters')
        return v

    @field_validator('password')
    def password_strong(cls, v):
        if len(v) < 8:
            raise ValueError('Password must be at least 8 characters')
        if not any(c.isupper() for c in v):
            raise ValueError('Password must contain uppercase letters')
        return v

    @field_validator('age')
    def age_valid(cls, v):
        if v < 18:
            raise ValueError('Must be at least 18 years old')
        return v

@app.post("/register")
async def register(user: UserCreate):
    return {"id": 1, "username": user.username}

Common patterns and best practices

• ✅ Use type hints for automatic validation

• ✅ Use Pydantic validators for business logic

• ✅ Provide clear error messages in validators

• ✅ Test validation with invalid inputs

• ✅ Return helpful error details to clients

• ✅ Use EmailStr for email validation

• ✅ Define constraints (min, max, regex patterns)

• ✅ Handle validation errors gracefully

🔑 Key Takeaways

• ✅ Understand the purpose of validation errors

• ✅ Know when to apply this pattern

• ✅ Recognize its benefits in real-world scenarios

• ✅ Be prepared to use it in your projects

Ready to explore more? Check out the advanced section for production patterns and edge cases.