Field validation exception custom exception information

[YueXiaWyl]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from fastapi import FastAPI, Query
@app.get("/items/")
async def read_items(filter_query: str = Query(..., min_length=10, max_length=100, error_msg="Custom exception information ")):
    return filter_query


if __name__ == '__main__':
    import uvicorn

    uvicorn.run(app, host="127.0.0.1", port=8000)

Description

When an exception occurs, custom information is captured through exception middleware and returned .
You can add an error_msg attribute to Query() to customize the exception that fails verification, so that it can be convenient and friendly to remind users .

Operating System

Windows

Operating System Details

No response

FastAPI Version

fastapi version = "0.110.0"

Pydantic Version

pydantic 2.7.3

Python Version

python 3.10.11

Additional Context

No response

[Kfir-G]

Hey @YueXiaWyl ,

In FastAPI, you can't directly pass a custom error_msg to the Query object, but you can still customize the error messages by handling validation exceptions yourself. The way to do this is by using FastAPI's exception handler to catch RequestValidationError and return your custom error message.

Here's an example of how you can do it:

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

app = FastAPI()

# Custom exception handler
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={"detail": "Custom exception: Query parameter must be between 10 and 100 characters."},
    )

@app.get("/items/")
async def read_items(filter_query: str = Query(..., min_length=10, max_length=100)):
    return filter_query

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="127.0.0.1", port=8000)

This code will catch any validation error (like when your query parameter is too short or too long) and return a custom error message instead of the default one.

So, when a user sends a query that doesn’t meet the validation criteria, they'll get something like:

{
  "detail": "Custom exception: Query parameter must be between 10 and 100 characters."
}

This way, you can make error messages more user-friendly and clear.

[YuexiaW]

Very happy to see your reply

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

app = FastAPI()


# If the validation fails, throwing an exception is not very user friendly.
# class User(BaseModel):
#     name: str = Field(..., min_length=5)
#     nickname: str = Field(...)
#     age: int = Field(..., gt=18)

# Further improvement: Although custom exception information can be implemented below,
# it requires a lot of code. I hope to use @field_validator to verify some complex data.
class User(BaseModel):
    name: str | None = None
    nickname: str | None = None
    age: int | None = None

    @field_validator("name")
    def check_name(cls, v):
        if v is None:
            raise ValueError("Please enter your username. The username must be longer than 5 characters.")
        if len(v) < 5:
            raise ValueError("Please enter your username. The username must be longer than 5 characters.")
        return v

    @field_validator("nickname")
    def check_nickname(cls, v):
        if v is None:
            raise ValueError("nickname can not be None")
        return v

    @field_validator("age")
    def check_age(cls, v):
        if v is None:
            raise ValueError("age can not be None")
        if v < 18:
            raise ValueError("age can not be less than 18")
        return v


# The following is the effect that we hope to achieve, 
# but pydantic does not support it at present. 
# For simple validation, use Fields directly. If it is a complex validation, use @field_validator. 
# I think the following method is what many web developers want.
# class User(BaseModel):
#     name: str = Field(..., min_length=5,
#                       error_msg="Please enter your username. The username must be longer than 5 characters.")
#     nickname: str = Field(..., error_msg="Please enter your nickname")
#     age: int = Field(..., gt=18, error_msg="age can not be less than 18")


@app.post("/create/user")
async def read_items(user: User):
    # 创建用户
    print(user.model_dump())
    # ...
    return "Success"


if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="127.0.0.1", port=8000)

I just wrote a simple case above. If you add multiple fields, you can use @field_validator to implement custom exceptions. Thank you, but if I just check the length of a string or the size of a number or whether it is empty, I can already do it through Field. However, the exception output when Field verification fails is not very user-friendly.Is there any way to achieve this?

[Kfir-G]

@YueXiaWyl See:

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

app = FastAPI()

class User(BaseModel):
    name: str = Field(..., min_length=5)
    nickname: str = Field(...)
    age: int = Field(..., gt=18)

    @field_validator("name")
    def check_name(cls, v):
        if len(v) < 5:
            raise ValueError("The username must be longer than 5 characters.")
        return v

    @field_validator("nickname")
    def check_nickname(cls, v):
        if v is None:
            raise ValueError("Nickname cannot be None.")
        return v

    @field_validator("age")
    def check_age(cls, v):
        if v < 18:
            raise ValueError("Age cannot be less than 18.")
        return v


@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    errors = exc.errors()
    custom_errors = []
    
    for error in errors:
        field = error.get("loc", [""])[-1]
        msg = error.get("msg", "")
        custom_errors.append(f"Error in '{field}': {msg}")
    
    return JSONResponse(
        status_code=422,
        content={"errors": custom_errors},
    )

@app.post("/create/user")
async def create_user(user: User):
    return {"message": "User created successfully"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="127.0.0.1", port=8000)

You can customize the error response by creating a global exception handler for RequestValidationError, and uses Field for simple validations (like min_length and gt), and @field_validator for more complex checks if needed

[YuriiMotov]

You can use WrapValidator for this reason:

from typing import Annotated, Any
from fastapi import FastAPI, Query
from pydantic import ValidationError, ValidatorFunctionWrapHandler, WrapValidator


app = FastAPI()


def override_err(value: Any, handler: ValidatorFunctionWrapHandler) -> str:
    try:
        return handler(value)
    except ValidationError:
        raise ValueError("CUSTOM MESSAGE")


@app.get("/items/")
async def read_items(
    filter_query: Annotated[
        str, Query(min_length=10, max_length=100), WrapValidator(override_err)
    ],
):
    return filter_query

Or, configurable version:

from typing import Annotated, Any
from fastapi import FastAPI, Query
from pydantic import ValidationError, ValidatorFunctionWrapHandler, WrapValidator


app = FastAPI()


def wrap_validation_error(msg_prefix: str) -> WrapValidator:
    def add_msg(value: Any, handler: ValidatorFunctionWrapHandler) -> str:
        try:
            return handler(value)
        except ValidationError as err:
            raise ValueError(f"{msg_prefix}: {err}")

    return WrapValidator(add_msg)


@app.get("/items/")
async def read_items(
    filter_query: Annotated[
        str,
        Query(min_length=10, max_length=100),
        wrap_validation_error("Custom exception information "),
    ],
):
    return filter_query