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,
    InvalidFacetFilterError,
    InvalidOrderFieldError,
    generate_error_responses,
    init_exceptions_handlers,
)

fastapi_toolsets.exceptions.exceptions.ApiException

Bases: Exception

Base exception for API errors with structured response.

__init__(detail=None, *, desc=None, data=None)

Initialize the exception.

Parameters:

Name Type Description Default
detail str | None

Optional human-readable message

 None
desc str | None

Optional per-instance override for the description field in the HTTP response body.

 None
data Any

Optional per-instance override for the data field in the HTTP response body.

 None

fastapi_toolsets.exceptions.exceptions.UnauthorizedError

Bases: ApiException

HTTP 401 - User is not authenticated.

__init__(detail=None, *, desc=None, data=None)

Initialize the exception.

Parameters:

Name Type Description Default
detail str | None

Optional human-readable message

 None
desc str | None

Optional per-instance override for the description field in the HTTP response body.

 None
data Any

Optional per-instance override for the data field in the HTTP response body.

 None

fastapi_toolsets.exceptions.exceptions.ForbiddenError

Bases: ApiException

HTTP 403 - User lacks required permissions.

__init__(detail=None, *, desc=None, data=None)

Initialize the exception.

Parameters:

Name Type Description Default
detail str | None

Optional human-readable message

 None
desc str | None

Optional per-instance override for the description field in the HTTP response body.

 None
data Any

Optional per-instance override for the data field in the HTTP response body.

 None

fastapi_toolsets.exceptions.exceptions.NotFoundError

Bases: ApiException

HTTP 404 - Resource not found.

__init__(detail=None, *, desc=None, data=None)

Initialize the exception.

Parameters:

Name Type Description Default
detail str | None

Optional human-readable message

 None
desc str | None

Optional per-instance override for the description field in the HTTP response body.

 None
data Any

Optional per-instance override for the data field in the HTTP response body.

 None

fastapi_toolsets.exceptions.exceptions.ConflictError

Bases: ApiException

HTTP 409 - Resource conflict.

__init__(detail=None, *, desc=None, data=None)

Initialize the exception.

Parameters:

Name Type Description Default
detail str | None

Optional human-readable message

 None
desc str | None

Optional per-instance override for the description field in the HTTP response body.

 None
data Any

Optional per-instance override for the data field in the HTTP response body.

 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 model class that has no searchable fields configured.

 required

fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError

Bases: ApiException

Raised when filter_by contains a key not declared in facet_fields.

__init__(key, valid_keys)

Initialize the exception.

Parameters:

Name Type Description Default
key str

The unknown filter key provided by the caller.

 required
valid_keys set[str]

Set of valid keys derived from the declared facet_fields.

 required

fastapi_toolsets.exceptions.exceptions.InvalidOrderFieldError

Bases: ApiException

Raised when order_by contains a field not in the allowed order fields.

__init__(field, valid_fields)

Initialize the exception.

Parameters:

Name Type Description Default
field str

The unknown order field provided by the caller.

 required
valid_fields list[str]

List of valid field names.

 required

fastapi_toolsets.exceptions.exceptions.generate_error_responses(*errors)

Generate OpenAPI response documentation for exceptions.

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.

fastapi_toolsets.exceptions.handler.init_exceptions_handlers(app)

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

Parameters:

Name Type Description Default
app FastAPI

FastAPI application instance.

 required

Returns:

Type Description
FastAPI

The same FastAPI instance (for chaining).