Skip to content

exceptions

Here's the reference for all exception classes and handler utilities.

You can import them directly from fastapi_toolsets.exceptions:

from fastapi_toolsets.exceptions import (
    ApiException,
    UnauthorizedError,
    ForbiddenError,
    NotFoundError,
    ConflictError,
    NoSearchableFieldsError,
    generate_error_responses,
    init_exceptions_handlers,
)

fastapi_toolsets.exceptions.exceptions.ApiException

Bases: Exception

Base exception for API errors with structured response.

Subclass this to create custom API exceptions with consistent error format. The exception handler will use api_error to generate the response.

Example 
class CustomError(ApiException):
    api_error = ApiError(
        code=400,
        msg="Bad Request",
        desc="The request was invalid.",
        err_code="CUSTOM-400",
    )

__init__(detail=None)

Initialize the exception.

Parameters:

Name Type Description Default
detail str | None

Optional override for the error message

 None

fastapi_toolsets.exceptions.exceptions.UnauthorizedError

Bases: ApiException

HTTP 401 - User is not authenticated.

__init__(detail=None)

Initialize the exception.

Parameters:

Name Type Description Default
detail str | None

Optional override for the error message

 None

fastapi_toolsets.exceptions.exceptions.ForbiddenError

Bases: ApiException

HTTP 403 - User lacks required permissions.

__init__(detail=None)

Initialize the exception.

Parameters:

Name Type Description Default
detail str | None

Optional override for the error message

 None

fastapi_toolsets.exceptions.exceptions.NotFoundError

Bases: ApiException

HTTP 404 - Resource not found.

__init__(detail=None)

Initialize the exception.

Parameters:

Name Type Description Default
detail str | None

Optional override for the error message

 None

fastapi_toolsets.exceptions.exceptions.ConflictError

Bases: ApiException

HTTP 409 - Resource conflict.

__init__(detail=None)

Initialize the exception.

Parameters:

Name Type Description Default
detail str | None

Optional override for the error message

 None

fastapi_toolsets.exceptions.exceptions.NoSearchableFieldsError

Bases: ApiException

Raised when search is requested but no searchable fields are available.

__init__(model)

Initialize the exception.

Parameters:

Name Type Description Default
model type

The SQLAlchemy model class that has no searchable fields

 required

fastapi_toolsets.exceptions.exceptions.generate_error_responses(*errors)

Generate OpenAPI response documentation for exceptions.

Use this to document possible error responses for an endpoint.

Parameters:

Name Type Description Default
*errors type[ApiException]

Exception classes that inherit from ApiException

 ()

Returns:

Type Description
dict[int | str, dict[str, Any]]

Dict suitable for FastAPI's responses parameter
Example 
from fastapi_toolsets.exceptions import generate_error_responses, UnauthorizedError, ForbiddenError

@app.get(
    "/admin",
    responses=generate_error_responses(UnauthorizedError, ForbiddenError)
)
async def admin_endpoint():
    ...

fastapi_toolsets.exceptions.handler.init_exceptions_handlers(app)

Register exception handlers and custom OpenAPI schema on a FastAPI app.

Installs handlers for :class:ApiException, validation errors, and unhandled exceptions, and replaces the default 422 schema with a consistent error format.

Parameters:

Name Type Description Default
app FastAPI

FastAPI application instance

 required

Returns:

Type Description
FastAPI

The same FastAPI instance (for chaining)
Example 
from fastapi import FastAPI
from fastapi_toolsets.exceptions import init_exceptions_handlers

app = FastAPI()
init_exceptions_handlers(app)