Skip to content
You're not viewing the latest version. Click here to go to latest.

# `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.

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.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.

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)