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