FastAPI Validation Override

FastAPI returns 422 Unprocessable Entity for every request validation failure. Many APIs, client teams, and HTTP standards treat 400 Bad Request as the correct status code for malformed input. Fixing this in FastAPI requires wiring a custom exception handler and updating the OpenAPI schema separately. override_validation_error does both in a single call.

Features

• Single call: patches runtime exception handling and the OpenAPI schema at once
• Any status code: use 400, 409, or any valid code instead of 422
• anyOf merge: when a route already declares a response at the target code, the validation error schema is merged rather than overwritten
• Independent of a custom 422: if a route keeps its own, non-validation 422 response, it's left untouched and the validation schema is still documented at the target code
• Custom openapi preserved: wraps any app.openapi function already installed and applies the patch on top of its output
• Bring your own handler: handle_exceptions=False skips the built-in handler while still patching the schema
• Idempotent: safe to call multiple times on the same app instance
• No-op guard: status_code=422 leaves FastAPI behavior unchanged

Requirements

• Python 3.10+
• FastAPI 0.120.0+

Installation

pip install fastapi-validation-override
# or
uv add fastapi-validation-override

Quick start

from fastapi import FastAPI
from pydantic import BaseModel

from fastapi_validation_override import override_validation_error

app = FastAPI()


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


@app.post("/items")
async def create_item(item: Item) -> dict[str, object]:
    return item.model_dump()


override_validation_error(app)
# POST /items with invalid fields -> 400 Bad Request {"detail": [...]}

The {"detail": [...]} body is identical to FastAPI's default 422 response. Only the status code changes.

To use a different code, pass status_code:

override_validation_error(app, status_code=409)

Reference

override_validation_error

override_validation_error(app, status_code=400, handle_exceptions=True, merge_target_response=True)

patch_422_responses

patch_422_responses(schema, target_code, merge_target_response=True)

The schema-patching logic that override_validation_error uses internally, exposed as a standalone function for advanced use cases, such as patching a schema inside your own custom app.openapi function without going through override_validation_error. Mutates schema in place and also returns it.

from fastapi_validation_override import patch_422_responses

schema = app.openapi()
patch_422_responses(schema, "400")

What happens to 422 and what happens to target_code are decided independently: a FastAPI-generated 422 validation response is removed, any other response already declared at 422 is left untouched, and routes that need validation always get it documented at target_code, synthesized from FastAPI's own schema components if nothing is there yet. See Independent 422 handling below.

Custom exception handler

Set handle_exceptions=False when you need a custom response body or additional logic. The OpenAPI schema is still patched.

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

from fastapi_validation_override import override_validation_error

app = FastAPI()


@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
    return JSONResponse(
        status_code=400,
        content={"message": "Validation failed", "errors": exc.errors()},
    )


@app.post("/items")
async def create_item(item: Item) -> dict[str, object]:
    return item.model_dump()


override_validation_error(app, status_code=400, handle_exceptions=False)

Preserving a custom app.openapi

Call override_validation_error after assigning your custom openapi function. The library captures app.openapi at call time and wraps it, so the order matters.

from typing import Any

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

from fastapi_validation_override import override_validation_error

app = FastAPI()


def custom_openapi() -> dict[str, Any]:
    if app.openapi_schema:
        return app.openapi_schema
    schema = get_openapi(title="My API", version="1.0.0", routes=app.routes)
    schema["info"]["x-logo"] = {"url": "https://example.com/logo.png"}
    app.openapi_schema = schema
    return schema


app.openapi = custom_openapi  # type: ignore[method-assign]
override_validation_error(app)  # must come after

Merging with an existing response at the target code

When a route already declares a response at the target status code, override_validation_error merges the schemas using anyOf instead of overwriting the existing one.

class OutOfStockError(BaseModel):
    message: str
    item_name: str


@app.post("/items", responses={400: {"model": OutOfStockError, "description": "Out of stock"}})
async def create_item(item: Item) -> dict[str, object]:
    return item.model_dump()


override_validation_error(app)
# schema at 400: anyOf: [HTTPValidationError, OutOfStockError]

The merge only touches the schema (the JSON Schema union). It doesn't generate an OpenAPI example/examples value for either variant, so tools like Swagger UI won't show a distinct sample payload for OutOfStockError versus the validation error unless you declare one yourself (e.g. via a field default, or model_config = ConfigDict(json_schema_extra={"example": ...})) — the library can't safely invent one for a model it knows nothing about.

Set merge_target_response=False to leave a response you already declared at the target code completely untouched instead of merging it with anyOf:

override_validation_error(app, merge_target_response=False)

Independent 422 handling

A route can keep its own, non-validation 422 response. As long as the route has a body or parameters that FastAPI validates, it's left untouched at 422, and the validation error is still documented at the target code — independently of what occupies 422.

class OutOfStockError(BaseModel):
    error_code: str
    item_name: str


@app.post("/items", responses={422: {"model": OutOfStockError, "description": "Item is out of stock"}})
async def create_item(item: Item) -> dict[str, object]:
    return item.model_dump()


override_validation_error(app)
# 422 still documents OutOfStockError, untouched.
# 400 is added automatically, documenting the validation error schema.

This also applies at runtime. If this route receives a request that fails validation, the exception handler still returns target_code (400 by default), not the custom 422 — responses={422: ...} only affects documentation, it never changes which exception handler FastAPI dispatches to. Your custom 422 response is for errors you raise yourself (like OutOfStockError above), not for request validation failures.

Note: when the validation schema is synthesized this way, HTTPValidationError and ValidationError are added to components.schemas if they aren't already there. If you snapshot-test your OpenAPI schema, expect these two component definitions to appear the first time this happens.

Examples

Runnable examples are in the examples/ directory:

Release Notes

RELEASE_NOTES

License

MIT