Plans to provide `ResponseModel` customization?

[UnoYakshi]

Current ResponseModel provides 5 meta-fields:

{
  "data": {
    // Actual endpoint's response data...
  },
  "status": "SUCCESS",
  "message": "Hers's your user, pal!",
  "error_code": null,
  "description": "User found."
}

But, for example, I'd prefer to have:

for success

{
  "request_id": "UUID from service/proxy/gateway/etc.",
  "payload": {
    // Actual data...
  },
  "detail": "User [UUID] found.",  // Or even `null`?..
  "error": null
}

for failure

{
  "request_id": "UUID from service/proxy/gateway/etc.",
  "payload": null,
  "detail": "Could not retrieve a User [UUID] with such parameters...",
  "error": {
    "code": "VAL-422",
    "detail": [
      {
        "type": "int_parsing",
        "loc": [
          "query",
          "limit"
        ],
        "msg": "Input should be a valid integer, unable to parse string as an integer",
        "input": "dw"
      },
      {
        "type": "int_parsing",
        "loc": [
          "query",
          "itemsPerPage"
        ],
        "msg": "Input should be a valid integer, unable to parse string as an integer",
        "input": "pops"
      }
    ]
  }
}

Considering ResponseModel implementation, I see no way but to make a custom response schema + rewrite some inner logic (injection/rewriting). So I wonder if there are any plans on making customizable meta-fields: changing fields' names, adding new fields, hiding/removing old fields. If and only if it's possible, of course.

[akutayural]

Thanks a lot for taking the time to review the library in detail and for asking this very valid question.

You are absolutely right that error response contracts vary significantly from team to team. When I initially designed APIException, my goal was to reduce this fragmentation by providing a single, unified response model for both success and error cases. This keeps the integration plug and play and allows frontend clients to handle all scenarios using a single data model. In addition, errors can be easily traced using only the error code and endpoint information. I also believe that not exposing overly detailed validation errors by default improves security.

At the same time, I want to respect the IETF standards. The library currently includes an RFC 7807 model, but in the next patch I plan to remove RFC 7807 support and migrate to the newer RFC 9457 format. Along with this, I will provide an optional Problem Details output based on RFC 9457.

Furthermore, the RFC 9457 model will be made extensible. Problem Details is intentionally minimal and explicitly allows extension fields. In practice, many APIs require additional fields such as request_id, error_code, or structured validation details. To address this, the plan is as follows:
• The existing default unified response model will remain unchanged (no breaking changes; plug and play stays intact).
• An optional RFC 9457-compliant adapter or response format will be added.
• A clean mechanism will be provided for users to add extension fields or plug in their own response schema (custom adapter or custom model), since many teams need to comply with strict corporate response contracts.

If RFC 9457 is provided in an extensible way and allows users to attach the fields they need, I believe it should also cover your use case. I cannot implement a response structure that exactly matches every individual preference, as error response formats differ widely across teams. In fact, APIException was initially created to solve this exact problem by defining a single response standard for all success and error cases. However, combining RFC 9457 with extensibility for custom fields should result in a solution that works for the majority of use cases, including yours.

This will be included in the next patch.

[UnoYakshi]

Thank you for the and quick and detailed reply!

Validation (422) details

I also believe that not exposing overly detailed validation errors by default improves security.

I do understand there are certain security-related cases at hand. However, when an end user is filling a web-form, it'd be a pain for frontend/UX to either not show exact problems (multiple) at the same moment, or not to show anything to identify what fields are affected at all. For the sake of simplicity, let's pretend frontend's fields validation is passed (correct or not is out of scope).
Hence, I wonder if you can share your point of view in that regard. Well, aside from there always will be trade-offs between ease-of-use and security.

RFC 9457

in the next patch I plan to remove RFC 7807 support and migrate to the newer RFC 9457 format

That's really great to hear!

Successful (~200) response schema customization

The existing default unified response model will remain unchanged (no breaking changes; plug and play stays intact).

A clean mechanism will be provided for users to add extension fields or plug in their own response schema (custom adapter or custom model), since many teams need to comply with strict corporate response contracts.

I'm a bit confused. Do you mean for successful response schemas/models, too, right?

We are now planning to introduce infrastructural IDs (request, correlation, snap). And that's exactly what I'd like [to feed FastAPI app with and] to receive it back in the root of response body, not in the error details:

{
  "requestId": "2e006570-7640-4827-a615-75bebff64ace",
  "status": "SUCCESS",
  "message": "Everything's good!",
  // Other 200-ish fields...
}

[akutayural]

Hi @UnoYakshi, Thanks for the detailed response.

Validation (422) details

I do understand there are certain security-related cases at hand. However, when an end user is filling a web-form, it'd be a pain for frontend/UX to either not show exact problems (multiple) at the same moment, or not to show anything to identify what fields are affected at all. For the sake of simplicity, let's pretend frontend's fields validation is passed (correct or not is out of scope).
Hence, I wonder if you can share your point of view in that regard. Well, aside from there always will be trade-offs between ease-of-use and security.

Yes, as you mentioned, there will always be trade-offs between security and ease of use.
I intended to support both, which is why validation messages are included in the default Response Schema, specifically in the description field.

I've added a new example in the repo about that /examples/fastapi_usage.py POST /user/{user_id} endpoint. In the example, the body of the request waits for some_int_id; however, we provide a string.

{
  "data": null,
  "status": "FAIL",
  "message": "Validation Error",
  "error_code": "VAL-422",
  "description": "Input should be a valid integer, unable to parse string as an integer"
}

As you can see above, I have already sent the validation error message to the Frontend in the description field and also logged it as below.

Validation error log

[2026-02-01 15:26:51] WARNING in api_exception: Validation Error: Input should be a valid integer, unable to parse string as an integer
Traceback:
Traceback (most recent call last):
  File "/Users/kutay/Desktop/Projects/APIException/APIException/venv/lib/python3.10/site-packages/starlette/_exception_handler.py", line 42, in wrapped_app
    await app(scope, receive, sender)
  File "/Users/kutay/Desktop/Projects/APIException/APIException/venv/lib/python3.10/site-packages/starlette/routing.py", line 75, in app
    response = await f(request)
  File "/Users/kutay/Desktop/Projects/APIException/APIException/venv/lib/python3.10/site-packages/fastapi/routing.py", line 347, in app
    raise validation_error
fastapi.exceptions.RequestValidationError: [
  {
    'type': 'int_parsing',
    'loc': ('body', 'some_int_id'),
    'msg': 'Input should be a valid integer, unable to parse string as an integer',
    'input': 'test'
  }
]

meta:
│ event          : validation_error
│ path           : /user/312
│ method         : POST
│ client_ip      : 127.0.0.1
│ http_version   : 1.1
│ error_count    : 1
│ first_error    : Input should be a valid integer, unable to parse string as an integer
│ masked_user_id : user-us
│ service        : billing-service
│ has_exc        : True
│ exc_type       : RequestValidationError

INFO: 127.0.0.1:57443 - "POST /user/312 HTTP/1.1" 422 Unprocessable Entity

So the validation error itself is fully known to the frontend; only the exact field location is intentionally not exposed.

This strikes a reasonable balance between security and usability.
The frontend still receives enough information to understand what went wrong and react accordingly, while avoiding exposing internal request schemas or detailed validation paths that are not strictly necessary for client-side handling. While the frontend does not receive schema-level details, backend engineers can clearly see the exact cause and location of the error through structured logs.

The data field is also kept flexible by design; if more granular error details are required, they can be safely included there without changing the core response structure.

Successful (~200) response schema customisation

I'm a bit confused. Do you mean for successful response schemas/models, too, right?

No, I did not mean that. I am not planning to change the structure of the successful response schema itself.

As mentioned earlier, the core idea of this repository is to provide a single, unified response schema and keep it plug-and-play by default. That contract will remain unchanged and stable.

That said, if a team needs to shape the successful response according to their own corporate or infrastructural requirements, such as introducing root-level identifiers like requestId, the library can still be useful in that scenario.

For example, if you want a response structure like:

{
  "requestId": "2e006570-7640-4827-a615-75bebff64ace",
  "status": "SUCCESS",
  "message": "Everything's good!"
  "error_code": null,
  "description": "Good"
}

You can do it like below:

from __future__ import annotations

import uuid
from typing import Generic, Optional, TypeVar

from fastapi import FastAPI, Request
from pydantic import BaseModel, Field

from api_exception import register_exception_handlers, ResponseModel
from api_exception.enums import ExceptionStatus

app = FastAPI()
register_exception_handlers(app)

DataT = TypeVar("DataT")


class CustomResponseModel(ResponseModel[DataT], Generic[DataT]):
    request_id: Optional[str] = Field(
        default=None,
        alias="requestId",
        description="Infrastructure request id.",
    )


@app.middleware("http")
async def ensure_request_id(request: Request, call_next):
    # Use incoming header if present, otherwise generate one
    rid = request.headers.get("x-request-id") or str(uuid.uuid4())

    # Store on request state so endpoints can access it
    request.state.request_id = rid

    # Continue request
    response = await call_next(request)

    return response


class UserOut(BaseModel):
    id: int
    username: str


@app.get("/user/{user_id}", response_model=CustomResponseModel[UserOut])
async def get_user(user_id: int, request: Request):
    data = UserOut(id=user_id, username="Kutay")

    return CustomResponseModel[UserOut](
        request_id=request.state.request_id,  # returned as "requestId"
        data=data,
        status=ExceptionStatus.SUCCESS,
        message="Everything's good!",
        description="User retrieved successfully.",
    )

So whenever you want to return 200 with your custom logic, you can always return CustomResponseModel, which inherits ResponseModel from api_exception, and have your own business logic.

You don't have to write class CustomResponseModel(ResponseModel[DataT], Generic[DataT]):, instead you can only write class CustomResponseModel(ResponseModel[DataT]): . This is added only for the type checker.

In short, after inheriting from ResponseModel, you can add any extra business fields you need and return them at the root level. This works for both successful (~200) and error responses, without changing the default Response Schema for everyone.

One Extra Example for Error Cases

from __future__ import annotations

import uuid
import traceback
from typing import Any, Generic, Optional, TypeVar, List, Callable

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

from api_exception import (
    register_exception_handlers,
    ResponseModel,
    ExceptionCode,
    ExceptionStatus,
)

app = FastAPI()

# Disable library fallback middleware so we can implement our own handlers/middleware
register_exception_handlers(app, use_fallback_middleware=False)

DataT = TypeVar("DataT")


class CustomResponseModel(ResponseModel[DataT], Generic[DataT]):
    request_id: Optional[str] = Field(default=None, description="Infrastructure request id.")
    error: Optional[List[dict[str, Any]]] = Field(
        default=None,
        description="Raw Pydantic validation errors (exc.errors()).",
    )


@app.middleware("http")
async def ensure_request_id(request: Request, call_next):
    rid = request.headers.get("x-request-id") or str(uuid.uuid4())
    request.state.request_id = rid
    response = await call_next(request)
    response.headers["x-request-id"] = rid
    return response


@app.exception_handler(RequestValidationError)
async def custom_validation_handler(request: Request, exc: RequestValidationError):
    err = ExceptionCode.VALIDATION_ERROR
    first_msg = exc.errors()[0].get("msg", err.description) if exc.errors() else err.description

    return JSONResponse(
        status_code=422,
        content=CustomResponseModel(
            request_id=request.state.request_id,
            data=None,
            status=ExceptionStatus.FAIL,
            message=err.message,
            error_code=err.error_code,
            description=first_msg,
            error=exc.errors(),  # automatic
        ).model_dump(exclude_none=False),
    )


@app.middleware("http")
async def custom_fallback_middleware(request: Request, call_next: Callable):
    try:
        return await call_next(request)
    except Exception:
        err = ExceptionCode.INTERNAL_SERVER_ERROR
        tb = traceback.format_exc()

        # (optional) log tb here

        return JSONResponse(
            status_code=500,
            content=CustomResponseModel(
                request_id=getattr(request.state, "request_id", None),
                data=None,
                status=ExceptionStatus.FAIL,
                message=err.message,
                error_code=err.error_code,
                description=err.description,
                error=[{"type": "unhandled_exception", "traceback": tb}],  # optional; or omit
            ).model_dump(exclude_none=False),
        )

Resulting responses

With the setup above, responses will look like the following.

Validation error (422)

{
  "request_id": "2e006570-7640-4827-a615-75bebff64ace",
  "data": null,
  "status": "FAIL",
  "message": "Validation Error",
  "error_code": "VAL-422",
  "description": "Input should be a valid integer, unable to parse string as an integer",
  "error": [
    {
      "type": "int_parsing",
      "loc": ["query", "limit"],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "dw"
    },
    {
      "type": "int_parsing",
      "loc": ["query", "itemsPerPage"],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "pops"
    }
  ]
}

In this case:
• description provides a concise, user-facing summary.
• error contains the raw Pydantic validation output (exc.errors()), populated automatically.
• No manual mapping of validation fields is required.

Unhandled exception (500)

{
  "request_id": "2e006570-7640-4827-a615-75bebff64ace",
  "data": null,
  "status": "FAIL",
  "message": "Internal Server Error",
  "error_code": "INT-500",
  "description": "An unexpected error occurred.",
  "error": [
    {
      "type": "unhandled_exception"
    }
  ]
}

In this case:
• The unified response contract is preserved.
• Infrastructure-level metadata (request_id) is still available.
• Detailed stack traces can remain in logs only (recommended for production), while the response stays minimal and safe.

[akutayural]

/examples/advanced_examples/fastapi_usage.py

I tried to explain how you can achieve what you want in this example. Please take a look at the exam. You can even copy-paste the structure

for success

{
  "request_id": "UUID from service/proxy/gateway/etc.",
  "payload": {
    // Actual data...
  },
  "detail": "User [UUID] found.",  // Or even `null`?..
  "error": null
}

Take a look at the first endpoint for that. GET /demo/validation

for failure

{
  "request_id": "UUID from service/proxy/gateway/etc.",
  "payload": null,
  "detail": "Could not retrieve a User [UUID] with such parameters...",
  "error": {
    "code": "VAL-422",
    "detail": [
      {
        "type": "int_parsing",
        "loc": [
          "query",
          "limit"
        ],
        "msg": "Input should be a valid integer, unable to parse string as an integer",
        "input": "dw"
      },
      {
        "type": "int_parsing",
        "loc": [
          "query",
          "itemsPerPage"
        ],
        "msg": "Input should be a valid integer, unable to parse string as an integer",
        "input": "pops"
      }
    ]
  }
}

Take a look at the second endpoint POST /demo/validation-body

@UnoYakshi, I believe, these examples might help you sort out the situation.

I run the example with:

• fastapi 0.115.4
• pydantic 2.12.5
• starlette 0.41.3