Raising an HTTPException as validation in a path operation with response_model of some Pydantic model results in an Internal Server Error. What is the correct approach?

[led3zma]

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, HTTPException
from pydantic import BaseModel

# db mock object for simplicity
childs = [
    {'id': 1, 'name': 'product1', 'barcode': '001'},
    {'id': 2, 'name': 'product2', 'barcode': '002'},
    {'id': 3, 'name': 'product3', 'barcode': '003'},
]

class ChildBase(BaseModel):
    name: str
    barcode: str

class ChildSchema(ChildBase):
    id: int

    class Config:
        from_attributes = True

app = FastAPI()

@app.get('/childs/{child_id}', tags=['child'], response_model=ChildSchema, status_code=200)
def get_child(child_id: int):
    child = next((item for item in childs if item["id"] == child_id), None)
    if not child:
        return HTTPException(status_code=404, detail='Child not found')
    return child

Description

Tried to simplify my code. Originally I query a database instead of a mock object but the result is the same.

I start testing the endpoint in the Swagger UI, passing the child_id parameter.
What I expect to happen is to get the response body of the query if the child_id exists like this:

{
  "name": "product2",
  "barcode": "002",
  "id": 2
}

And if the child_id doesn't exists, I expect this response body:

{
  "status_code": 404,
  "detail": "Child not found",
  "headers": null
}

However, the latter doesn't happen. Instead, I get an Internal Server Error with the following message in the logs:

fastapi.exceptions.ResponseValidationError: 3 validation errors:
  {'type': 'missing', 'loc': ('response', 'name'), 'msg': 'Field required', 'input': HTTPException(status_code=404, detail='Child not found')}
  {'type': 'missing', 'loc': ('response', 'barcode'), 'msg': 'Field required', 'input': HTTPException(status_code=404, detail='Child not found')}
  {'type': 'missing', 'loc': ('response', 'id'), 'msg': 'Field required', 'input': HTTPException(status_code=404, detail='Child not found')}

This is solved pretty easily if I remove the response_model=ChildSchema from the path operations parameter. However, the detail that bothers me about this is that if I do this then in the response body documentation in the Swagger UI doesn't show the correct example value. It shows the default "string" instead of the full response body of the Pydantic model.

I understand there are some mechanism to override the exception handling methods in FastAPI, but I'm a bit lost and confused with some concepts. Is there something I'm missing? Or is there a better way of doing this with both the request_model validation and returning an error in case of it?

Operating System

Linux, Windows

Operating System Details

No response

FastAPI Version

0.111.0

Pydantic Version

2.7.1

Python Version

3.10.12

Additional Context

No response

[Kludex]

Raise, not return.

[led3zma]

Well that went over my head for a few hours. Thank you very much.