Let JSONResponse accept a custom json encoder from standard json library

[gregorio-clara]

I was using some validators and exception handlers while working on an API (using FastAPI) when I found that the starlette JSONResponse class (which is used by default by FastAPI) doesn't let you pass a custom encoder to manage the content argument.

My script is something like this:

# api.py

import json
from typing import Annotated

from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import (
    JSONResponse,
)  # Same as from starlette.responses import JSONResponse
from pydantic import BaseModel
from pydantic.functional_validators import BeforeValidator
from starlette import status


async def request_validation_exception_handler(
    request: Request, exc: RequestValidationError
):
    status_code = status.HTTP_422_UNPROCESSABLE_ENTITY
    content = {
        "error_type": "Unprocessable Entity",
        "status_code": status_code,
        "detail": exc.errors(),
        "path": request.url.path,
    }
    return JSONResponse(content=content, status_code=status_code)


def convert_int_to_str(integer: int) -> str:
    """
    Converts integers to strings.

    Params
    ------
    integer: int
        integer to be converted.

    Returns
    -------
    string: str
        string made from integer.
    """

    if isinstance(integer, int):
        return str(integer)
    raise ValueError("Invalid value, it is not an integer.")


class ProcessReceiptRequest(BaseModel):
    company_id: Annotated[str, BeforeValidator(convert_int_to_str)]
    amount: float
    date: str


app = FastAPI()
app.add_exception_handler(RequestValidationError, request_validation_exception_handler)

@app.post("/receipt/process")
async def process_receipt(request: ProcessReceiptRequest) -> dict:
    request = request.model_dump()
    # Some process
    return {"receipt_id": "149706"}  # Dummy response

If I run it uvicorn api:app --port 8080 and send a post request with a "wrong" company_id data-type to the /receipt/process endpoint

curl -X "POST" \
	'http://localhost:8080/receipt/process' \
	-H 'accept: application/json' \
	-H 'Content-Type: application/json' \
	-d '{"company_id": 1.2, "amount": 59.98, "date": "2025-08-30"}'

then I get a TypeError: Object of type ValueError is not JSON serializable, which is the due to the fact that the convert_int_to_str raises a ValueError that is handled and passed to the JSONResponse class in the content's detail field as exc.errors()

I found a solution by constructing a custom JSON encoder that can JSON serialize the exceptions by passing it to the cls argument from the json.dumps method and loading it back to a python dict with json.loads method. Which looks something like this (by modifying the handler)

class CustomJSONEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, Exception):
            return obj.__class__.__name__
        return super(CustomJSONEncoder, self).default(obj)


async def request_validation_exception_handler(
    request: Request, exc: RequestValidationError
):
    status_code = status.HTTP_422_UNPROCESSABLE_ENTITY
    content = {
        "error_type": "Unprocessable Entity",
        "status_code": status_code,
        "detail": json.loads(json.dumps(exc.errors(), cls=CustomJSONEncoder)),
        "path": request.url.path,
    }
    return JSONResponse(content=content, status_code=status_code)

When looking specifically into the JSONResponse class from starlette, I noticed that it already applies the json.dumps method to content in its render method (which is here).

And, even if your current documentation states to subclass JSONResponse and override the render method for custom JSON serialization (here), the orjson library doesn't handle exceptions in the serialization by default.

So, I think it might be much simpler/cleaner if we just add the support to the JSONResponse class to handle custom JSON encoders with the standard use of the json library and without the need to override the render method.

WDYT?

Btw, I already have a PR with implementation of this idea if you want to take a look :)

[bfontaine]

From a user perspective, isn’t it simpler to subclass JSONResponse once and reuse the class everywhere, rather than having to remember to import the custom encoder and pass it to every single return JSONResponse()?

# your_module/responses.py
from starlette.responses import JSONResponse as BaseJSONResponse


class JSONResponse(BaseJSONResponse):
    def render(self, content: Any) -> bytes:
        … 

# Then everywhere in your code:
from your_module.responses import JSONResponse

[gregorio-clara]

Yep, that's actually a really good point.