feat: rework Exception/ApiError (#107 )

* feat: rework Exception/ApiError * docs: update exceptions module * fix: docstring
feat: Raise NotFoundError instead of LookupError in wait_for_row_change (#105 )
2026-08-13 19:42:59 +00:00 · 2026-03-02 16:34:29 +01:00 · 2026-03-02 14:28:37 +01:00 · 2026-03-01 05:22:16 -05:00 · 2026-03-01 11:20:43 +01:00
20 changed files with 1105 additions and 196 deletions
@@ -1,6 +1,6 @@
 # Pagination & search

-This example builds an articles listing endpoint that supports **offset pagination**, **cursor pagination**, **full-text search**, and **faceted filtering** — all from a single `CrudFactory` definition.
+This example builds an articles listing endpoint that supports **offset pagination**, **cursor pagination**, **full-text search**, **faceted filtering**, and **sorting** — all from a single `CrudFactory` definition.

 ## Models

@@ -16,7 +16,7 @@ This example builds an articles listing endpoint that supports **offset paginati

 ## Crud

-Declare `facet_fields` and `searchable_fields` once on [`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory). All endpoints built from this class share the same defaults and can override them per call.
+Declare `searchable_fields`, `facet_fields`, and `order_fields` once on [`CrudFactory`](../reference/crud.md#fastapi_toolsets.crud.factory.CrudFactory). All endpoints built from this class share the same defaults and can override them per call.

 ```python title="crud.py"
 --8<-- "docs_src/examples/pagination_search/crud.py"
@@ -46,14 +46,14 @@ Declare `facet_fields` and `searchable_fields` once on [`CrudFactory`](../refere

 Best for admin panels or any UI that needs a total item count and numbered pages.

-```python title="routes.py:1:27"
--8<-- "docs_src/examples/pagination_search/routes.py:1:27"
+```python title="routes.py:1:36"
+--8<-- "docs_src/examples/pagination_search/routes.py:1:36"
 ```

 **Example request**

 ```
-GET /articles/offset?page=2&items_per_page=10&search=fastapi&status=published
+GET /articles/offset?page=2&items_per_page=10&search=fastapi&status=published&order_by=title&order=asc
 ```

 **Example response**
@@ -83,14 +83,14 @@ GET /articles/offset?page=2&items_per_page=10&search=fastapi&status=published

 Best for feeds, infinite scroll, or any high-throughput API where offset performance degrades.

-```python title="routes.py:30:45"
--8<-- "docs_src/examples/pagination_search/routes.py:30:45"
+```python title="routes.py:39:59"
+--8<-- "docs_src/examples/pagination_search/routes.py:39:59"
 ```

 **Example request**

 ```
-GET /articles/cursor?items_per_page=10&status=published
+GET /articles/cursor?items_per_page=10&status=published&order_by=created_at&order=desc
 ```

 **Example response**
@@ -295,6 +295,8 @@ Use `filter_by` to pass the client's chosen filter values directly — no need t
 Use [`filter_params()`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.filter_params) to generate a dict with the facet filter values from the query parameters:

 ```python
+from typing import Annotated
+
 from fastapi import Depends

 UserCrud = CrudFactory(
@@ -306,7 +308,7 @@ UserCrud = CrudFactory(
 async def list_users(
    session: SessionDep,
    page: int = 1,
-    filter_by: dict[str, list[str]] = Depends(UserCrud.filter_params()),
+    filter_by: Annotated[dict[str, list[str]], Depends(UserCrud.filter_params())],
 ) -> PaginatedResponse[UserRead]:
    return await UserCrud.offset_paginate(
        session=session,
@@ -323,6 +325,58 @@ GET /users?status=active&country=FR   → filter_by={"status": ["active"], "coun
 GET /users?role=admin&role=editor     → filter_by={"role": ["admin", "editor"]}  (IN clause)
 ```

+## Sorting
+
+!!! info "Added in `v1.3`"
+
+Declare `order_fields` on the CRUD class to expose client-driven column ordering via `order_by` and `order` query parameters.
+
+```python
+UserCrud = CrudFactory(
+    model=User,
+    order_fields=[
+        User.name,
+        User.created_at,
+    ],
+)
+```
+
+Call [`order_params()`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.order_params) to generate a FastAPI dependency that maps the query parameters to an [`OrderByClause`](../reference/crud.md#fastapi_toolsets.crud.factory.OrderByClause) expression:
+
+```python
+from typing import Annotated
+
+from fastapi import Depends
+from fastapi_toolsets.crud import OrderByClause
+
+@router.get("")
+async def list_users(
+    session: SessionDep,
+    order_by: Annotated[OrderByClause | None, Depends(UserCrud.order_params())],
+) -> PaginatedResponse[UserRead]:
+    return await UserCrud.offset_paginate(session=session, order_by=order_by)
+```
+
+The dependency adds two query parameters to the endpoint:
+
+| Parameter  | Type            |
+| ---------- | --------------- |
+| `order_by` | `str | null`   |
+| `order`    | `asc` or `desc` |
+
+```
+GET /users?order_by=name&order=asc   → ORDER BY users.name ASC
+GET /users?order_by=name&order=desc  → ORDER BY users.name DESC
+```
+
+An unknown `order_by` value raises [`InvalidOrderFieldError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidOrderFieldError) (HTTP 422).
+
+You can also pass `order_fields` directly to `order_params()` to override the class-level defaults without modifying them:
+
+```python
+UserOrderParams = UserCrud.order_params(order_fields=[User.name])
+```
+
 ## Relationship loading

 !!! info "Added in `v1.1`"
@@ -21,30 +21,37 @@ init_exceptions_handlers(app=app)
 This registers handlers for:

 - [`ApiException`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.ApiException) — all custom exceptions below
+- `HTTPException` — Starlette/FastAPI HTTP errors
 - `RequestValidationError` — Pydantic request validation (422)
 - `ResponseValidationError` — Pydantic response validation (422)
 - `Exception` — unhandled errors (500)

+It also patches `app.openapi()` to replace the default Pydantic 422 schema with a structured example matching the `ErrorResponse` format.
+
 ## Built-in exceptions

 | Exception | Status | Default message |
 |-----------|--------|-----------------|
 | [`UnauthorizedError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.UnauthorizedError) | 401 | Unauthorized |
 | [`ForbiddenError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.ForbiddenError) | 403 | Forbidden |
-| [`NotFoundError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NotFoundError) | 404 | Not found |
+| [`NotFoundError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NotFoundError) | 404 | Not Found |
 | [`ConflictError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.ConflictError) | 409 | Conflict |
-| [`NoSearchableFieldsError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NoSearchableFieldsError) | 400 | No searchable fields |
-| [`InvalidFacetFilterError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError) | 400 | Invalid facet filter |
+| [`NoSearchableFieldsError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.NoSearchableFieldsError) | 400 | No Searchable Fields |
+| [`InvalidFacetFilterError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError) | 400 | Invalid Facet Filter |
+| [`InvalidOrderFieldError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidOrderFieldError) | 422 | Invalid Order Field |
+
+### Per-instance overrides
+
+All built-in exceptions accept optional keyword arguments to customise the response for a specific raise site without changing the class defaults:
+
+| Argument | Effect |
+|----------|--------|
+| `detail` | Overrides both `str(exc)` (log output) and the `message` field in the response body |
+| `desc` | Overrides the `description` field |
+| `data` | Overrides the `data` field |

 ```python
-from fastapi_toolsets.exceptions import NotFoundError
-
-@router.get("/users/{id}")
-async def get_user(id: int, session: AsyncSession = Depends(get_db)):
-    user = await UserCrud.first(session=session, filters=[User.id == id])
-    if not user:
-        raise NotFoundError
-    return user
+raise NotFoundError(detail="User 42 not found", desc="No user with that ID exists in the database.")
 ```

 ## Custom exceptions
@@ -58,12 +65,51 @@ from fastapi_toolsets.schemas import ApiError
 class PaymentRequiredError(ApiException):
    api_error = ApiError(
        code=402,
-        msg="Payment required",
+        msg="Payment Required",
        desc="Your subscription has expired.",
-        err_code="PAYMENT_REQUIRED",
+        err_code="BILLING-402",
    )
 ```

+!!! warning
+    Subclasses that do not define `api_error` raise a `TypeError` at **class creation time**, not at raise time.
+
+### Custom `__init__`
+
+Override `__init__` to compute `detail`, `desc`, or `data` dynamically, then delegate to `super().__init__()`:
+
+```python
+class OrderValidationError(ApiException):
+    api_error = ApiError(
+        code=422,
+        msg="Order Validation Failed",
+        desc="One or more order fields are invalid.",
+        err_code="ORDER-422",
+    )
+
+    def __init__(self, *field_errors: str) -> None:
+        super().__init__(
+            f"{len(field_errors)} validation error(s)",
+            desc=", ".join(field_errors),
+            data={"errors": [{"message": e} for e in field_errors]},
+        )
+```
+
+### Intermediate base classes
+
+Use `abstract=True` when creating a shared base that is not meant to be raised directly:
+
+```python
+class BillingError(ApiException, abstract=True):
+    """Base for all billing-related errors."""
+
+class PaymentRequiredError(BillingError):
+    api_error = ApiError(code=402, msg="Payment Required", desc="...", err_code="BILLING-402")
+
+class SubscriptionExpiredError(BillingError):
+    api_error = ApiError(code=402, msg="Subscription Expired", desc="...", err_code="BILLING-402-EXP")
+```
+
 ## OpenAPI response documentation

 Use [`generate_error_responses`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.generate_error_responses) to add error schemas to your endpoint's OpenAPI spec:
@@ -78,8 +124,7 @@ from fastapi_toolsets.exceptions import generate_error_responses, NotFoundError,
 async def get_user(...): ...
 ```

-!!! info
-    The pydantic validation error is automatically added by FastAPI.
+Multiple exceptions sharing the same HTTP status code are grouped under one entry, each appearing as a named example keyed by its `err_code`. This keeps the OpenAPI UI readable when several error variants map to the same status.

 ---

@@ -13,6 +13,7 @@ from fastapi_toolsets.exceptions import (
    ConflictError,
    NoSearchableFieldsError,
    InvalidFacetFilterError,
+    InvalidOrderFieldError,
    generate_error_responses,
    init_exceptions_handlers,
 )
@@ -32,6 +33,8 @@ from fastapi_toolsets.exceptions import (

 ## ::: fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError

+## ::: fastapi_toolsets.exceptions.exceptions.InvalidOrderFieldError
+
 ## ::: fastapi_toolsets.exceptions.exceptions.generate_error_responses

 ## ::: fastapi_toolsets.exceptions.handler.init_exceptions_handlers
@@ -1,6 +1,9 @@
 from fastapi import FastAPI

+from fastapi_toolsets.exceptions import init_exceptions_handlers
+
 from .routes import router

 app = FastAPI()
+init_exceptions_handlers(app=app)
 app.include_router(router=router)
@@ -14,6 +14,8 @@ ArticleCrud = CrudFactory(
        Article.status,
        (Article.category, Category.name),
    ],
+    order_fields=[  # fields exposed for client-driven ordering
+        Article.title,
+        Article.created_at,
+    ],
 )
-
-ArticleFilters = ArticleCrud.filter_params()
@@ -1,9 +1,13 @@
+from typing import Annotated
+
 from fastapi import APIRouter, Depends, Query

+from fastapi_toolsets.crud import OrderByClause
 from fastapi_toolsets.schemas import PaginatedResponse

 from .crud import ArticleCrud
 from .db import SessionDep
+from .models import Article
 from .schemas import ArticleRead

 router = APIRouter(prefix="/articles")
@@ -12,10 +16,14 @@ router = APIRouter(prefix="/articles")
@router.get("/offset")
 async def list_articles_offset(
    session: SessionDep,
+    filter_by: Annotated[dict[str, list[str]], Depends(ArticleCrud.filter_params())],
+    order_by: Annotated[
+        OrderByClause | None,
+        Depends(ArticleCrud.order_params(default_field=Article.created_at)),
+    ],
    page: int = Query(1, ge=1),
    items_per_page: int = Query(20, ge=1, le=100),
    search: str | None = None,
-    filter_by: dict[str, list[str]] = Depends(ArticleCrud.filter_params()),
 ) -> PaginatedResponse[ArticleRead]:
    return await ArticleCrud.offset_paginate(
        session=session,
@@ -23,6 +31,7 @@ async def list_articles_offset(
        items_per_page=items_per_page,
        search=search,
        filter_by=filter_by or None,
+        order_by=order_by,
        schema=ArticleRead,
    )

@@ -30,10 +39,14 @@ async def list_articles_offset(
@router.get("/cursor")
 async def list_articles_cursor(
    session: SessionDep,
+    filter_by: Annotated[dict[str, list[str]], Depends(ArticleCrud.filter_params())],
+    order_by: Annotated[
+        OrderByClause | None,
+        Depends(ArticleCrud.order_params(default_field=Article.created_at)),
+    ],
    cursor: str | None = None,
    items_per_page: int = Query(20, ge=1, le=100),
    search: str | None = None,
-    filter_by: dict[str, list[str]] = Depends(ArticleCrud.filter_params()),
 ) -> PaginatedResponse[ArticleRead]:
    return await ArticleCrud.cursor_paginate(
        session=session,
@@ -41,5 +54,6 @@ async def list_articles_cursor(
        items_per_page=items_per_page,
        search=search,
        filter_by=filter_by or None,
+        order_by=order_by,
        schema=ArticleRead,
    )
@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "1.2.1"
+version = "1.3.0"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"
@@ -21,4 +21,4 @@ Example usage:
        return Response(data={"user": user.username}, message="Success")
 """

-__version__ = "1.2.1"
+__version__ = "1.3.0"
@@ -1,7 +1,7 @@
 """Generic async CRUD operations for SQLAlchemy models."""

 from ..exceptions import InvalidFacetFilterError, NoSearchableFieldsError
-from .factory import CrudFactory, JoinType, M2MFieldType
+from .factory import CrudFactory, JoinType, M2MFieldType, OrderByClause
 from .search import (
    FacetFieldType,
    SearchConfig,
@@ -16,5 +16,6 @@ __all__ = [
    "JoinType",
    "M2MFieldType",
    "NoSearchableFieldsError",
+    "OrderByClause",
    "SearchConfig",
 ]
@@ -21,10 +21,11 @@ from sqlalchemy.exc import NoResultFound
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import DeclarativeBase, QueryableAttribute, selectinload
 from sqlalchemy.sql.base import ExecutableOption
+from sqlalchemy.sql.elements import ColumnElement
 from sqlalchemy.sql.roles import WhereHavingRole

 from ..db import get_transaction
-from ..exceptions import NotFoundError
+from ..exceptions import InvalidOrderFieldError, NotFoundError
 from ..schemas import CursorPagination, OffsetPagination, PaginatedResponse, Response
 from .search import (
    FacetFieldType,
@@ -40,6 +41,7 @@ ModelType = TypeVar("ModelType", bound=DeclarativeBase)
 SchemaType = TypeVar("SchemaType", bound=BaseModel)
 JoinType = list[tuple[type[DeclarativeBase], Any]]
 M2MFieldType = Mapping[str, QueryableAttribute[Any]]
+OrderByClause = ColumnElement[Any] | QueryableAttribute[Any]


 def _encode_cursor(value: Any) -> str:
@@ -61,6 +63,7 @@ class AsyncCrud(Generic[ModelType]):
    model: ClassVar[type[DeclarativeBase]]
    searchable_fields: ClassVar[Sequence[SearchFieldType] | None] = None
    facet_fields: ClassVar[Sequence[FacetFieldType] | None] = None
+    order_fields: ClassVar[Sequence[QueryableAttribute[Any]] | None] = None
    m2m_fields: ClassVar[M2MFieldType | None] = None
    default_load_options: ClassVar[list[ExecutableOption] | None] = None
    cursor_column: ClassVar[Any | None] = None
@@ -176,6 +179,63 @@ class AsyncCrud(Generic[ModelType]):

        return dependency

+    @classmethod
+    def order_params(
+        cls: type[Self],
+        *,
+        order_fields: Sequence[QueryableAttribute[Any]] | None = None,
+        default_field: QueryableAttribute[Any] | None = None,
+        default_order: Literal["asc", "desc"] = "asc",
+    ) -> Callable[..., Awaitable[OrderByClause | None]]:
+        """Return a FastAPI dependency that resolves order query params into an order_by clause.
+
+        Args:
+            order_fields: Override the allowed order fields. Falls back to the class-level
+                ``order_fields`` if not provided.
+            default_field: Field to order by when ``order_by`` query param is absent.
+                If ``None`` and no ``order_by`` is provided, no ordering is applied.
+            default_order: Default order direction when ``order`` is absent
+                (``"asc"`` or ``"desc"``).
+
+        Returns:
+            An async dependency function named ``{Model}OrderParams`` that resolves to an
+            ``OrderByClause`` (or ``None``). Pass it to ``Depends()`` in your route.
+
+        Raises:
+            ValueError: If no order fields are configured on this CRUD class and none are
+                provided via ``order_fields``.
+            InvalidOrderFieldError: When the request provides an unknown ``order_by`` value.
+        """
+        fields = order_fields if order_fields is not None else cls.order_fields
+        if not fields:
+            raise ValueError(
+                f"{cls.__name__} has no order_fields configured. "
+                "Pass order_fields= or set them on CrudFactory."
+            )
+        field_map: dict[str, QueryableAttribute[Any]] = {f.key: f for f in fields}
+        valid_keys = sorted(field_map.keys())
+
+        async def dependency(
+            order_by: str | None = Query(
+                None, description=f"Field to order by. Valid values: {valid_keys}"
+            ),
+            order: Literal["asc", "desc"] = Query(
+                default_order, description="Sort direction"
+            ),
+        ) -> OrderByClause | None:
+            if order_by is None:
+                if default_field is None:
+                    return None
+                field = default_field
+            elif order_by not in field_map:
+                raise InvalidOrderFieldError(order_by, valid_keys)
+            else:
+                field = field_map[order_by]
+            return field.asc() if order == "asc" else field.desc()
+
+        dependency.__name__ = f"{cls.model.__name__}OrderParams"
+        return dependency
+
    @overload
    @classmethod
    async def create(  # pragma: no cover
@@ -415,7 +475,7 @@ class AsyncCrud(Generic[ModelType]):
        joins: JoinType | None = None,
        outer_join: bool = False,
        load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
        limit: int | None = None,
        offset: int | None = None,
    ) -> Sequence[ModelType]:
@@ -745,7 +805,7 @@ class AsyncCrud(Generic[ModelType]):
        joins: JoinType | None = None,
        outer_join: bool = False,
        load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
        page: int = 1,
        items_per_page: int = 20,
        search: str | SearchConfig | None = None,
@@ -766,7 +826,7 @@ class AsyncCrud(Generic[ModelType]):
        joins: JoinType | None = None,
        outer_join: bool = False,
        load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
        page: int = 1,
        items_per_page: int = 20,
        search: str | SearchConfig | None = None,
@@ -785,7 +845,7 @@ class AsyncCrud(Generic[ModelType]):
        joins: JoinType | None = None,
        outer_join: bool = False,
        load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
        page: int = 1,
        items_per_page: int = 20,
        search: str | SearchConfig | None = None,
@@ -937,7 +997,7 @@ class AsyncCrud(Generic[ModelType]):
        joins: JoinType | None = None,
        outer_join: bool = False,
        load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
        items_per_page: int = 20,
        search: str | SearchConfig | None = None,
        search_fields: Sequence[SearchFieldType] | None = None,
@@ -958,7 +1018,7 @@ class AsyncCrud(Generic[ModelType]):
        joins: JoinType | None = None,
        outer_join: bool = False,
        load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
        items_per_page: int = 20,
        search: str | SearchConfig | None = None,
        search_fields: Sequence[SearchFieldType] | None = None,
@@ -977,7 +1037,7 @@ class AsyncCrud(Generic[ModelType]):
        joins: JoinType | None = None,
        outer_join: bool = False,
        load_options: list[ExecutableOption] | None = None,
-        order_by: Any | None = None,
+        order_by: OrderByClause | None = None,
        items_per_page: int = 20,
        search: str | SearchConfig | None = None,
        search_fields: Sequence[SearchFieldType] | None = None,
@@ -1147,6 +1207,7 @@ def CrudFactory(
    *,
    searchable_fields: Sequence[SearchFieldType] | None = None,
    facet_fields: Sequence[FacetFieldType] | None = None,
+    order_fields: Sequence[QueryableAttribute[Any]] | None = None,
    m2m_fields: M2MFieldType | None = None,
    default_load_options: list[ExecutableOption] | None = None,
    cursor_column: Any | None = None,
@@ -1159,6 +1220,8 @@ def CrudFactory(
        facet_fields: Optional list of columns to compute distinct values for in paginated
            responses. Supports direct columns (``User.status``) and relationship tuples
            (``(User.role, Role.name)``). Can be overridden per call.
+        order_fields: Optional list of model attributes that callers are allowed to order by
+            via ``order_params()``. Can be overridden per call.
        m2m_fields: Optional mapping for many-to-many relationships.
            Maps schema field names (containing lists of IDs) to
            SQLAlchemy relationship attributes.
@@ -1252,6 +1315,7 @@ def CrudFactory(
            "model": model,
            "searchable_fields": searchable_fields,
            "facet_fields": facet_fields,
+            "order_fields": order_fields,
            "m2m_fields": m2m_fields,
            "default_load_options": default_load_options,
            "cursor_column": cursor_column,
@@ -10,6 +10,8 @@ from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 from sqlalchemy.orm import DeclarativeBase

+from .exceptions import NotFoundError
+
 __all__ = [
    "LockMode",
    "create_db_context",
@@ -216,7 +218,7 @@ async def wait_for_row_change(
        The refreshed model instance with updated values

    Raises:
-        LookupError: If the row does not exist or is deleted during polling
+        NotFoundError: If the row does not exist or is deleted during polling
        TimeoutError: If timeout expires before a change is detected

    Example:
@@ -237,7 +239,7 @@ async def wait_for_row_change(
    """
    instance = await session.get(model, pk_value)
    if instance is None:
-        raise LookupError(f"{model.__name__} with pk={pk_value!r} not found")
+        raise NotFoundError(f"{model.__name__} with pk={pk_value!r} not found")

    if columns is not None:
        watch_cols = columns
@@ -261,7 +263,7 @@ async def wait_for_row_change(
        instance = await session.get(model, pk_value)

        if instance is None:
-            raise LookupError(f"{model.__name__} with pk={pk_value!r} was deleted")
+            raise NotFoundError(f"{model.__name__} with pk={pk_value!r} was deleted")

        current = {col: getattr(instance, col) for col in watch_cols}
        if current != initial:
@@ -6,6 +6,7 @@ from .exceptions import (
    ConflictError,
    ForbiddenError,
    InvalidFacetFilterError,
+    InvalidOrderFieldError,
    NoSearchableFieldsError,
    NotFoundError,
    UnauthorizedError,
@@ -21,6 +22,7 @@ __all__ = [
    "generate_error_responses",
    "init_exceptions_handlers",
    "InvalidFacetFilterError",
+    "InvalidOrderFieldError",
    "NoSearchableFieldsError",
    "NotFoundError",
    "UnauthorizedError",
@@ -6,32 +6,46 @@ from ..schemas import ApiError, ErrorResponse, ResponseStatus


 class ApiException(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:
-        ```python
-        class CustomError(ApiException):
-            api_error = ApiError(
-                code=400,
-                msg="Bad Request",
-                desc="The request was invalid.",
-                err_code="CUSTOM-400",
-            )
-        ```
-    """
+    """Base exception for API errors with structured response."""

    api_error: ClassVar[ApiError]

-    def __init__(self, detail: str | None = None):
+    def __init_subclass__(cls, abstract: bool = False, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if not abstract and not hasattr(cls, "api_error"):
+            raise TypeError(
+                f"{cls.__name__} must define an 'api_error' class attribute. "
+                "Pass abstract=True when creating intermediate base classes."
+            )
+
+    def __init__(
+        self,
+        detail: str | None = None,
+        *,
+        desc: str | None = None,
+        data: Any = None,
+    ) -> None:
        """Initialize the exception.

        Args:
-            detail: Optional override for the error message
+            detail: Optional human-readable message
+            desc: Optional per-instance override for the ``description`` field
+                in the HTTP response body.
+            data: Optional per-instance override for the ``data`` field in the
+                HTTP response body.
        """
-        super().__init__(detail or self.api_error.msg)
+        updates: dict[str, Any] = {}
+        if detail is not None:
+            updates["msg"] = detail
+        if desc is not None:
+            updates["desc"] = desc
+        if data is not None:
+            updates["data"] = data
+        if updates:
+            object.__setattr__(
+                self, "api_error", self.__class__.api_error.model_copy(update=updates)
+            )
+        super().__init__(self.api_error.msg)


 class UnauthorizedError(ApiException):
@@ -92,14 +106,15 @@ class NoSearchableFieldsError(ApiException):
        """Initialize the exception.

        Args:
-            model: The SQLAlchemy model class that has no searchable fields
+            model: The model class that has no searchable fields configured.
        """
        self.model = model
-        detail = (
-            f"No searchable fields found for model '{model.__name__}'. "
-            "Provide 'search_fields' parameter or set 'searchable_fields' on the CRUD class."
+        super().__init__(
+            desc=(
+                f"No searchable fields found for model '{model.__name__}'. "
+                "Provide 'search_fields' parameter or set 'searchable_fields' on the CRUD class."
+            )
        )
-        super().__init__(detail)


 class InvalidFacetFilterError(ApiException):
@@ -116,16 +131,41 @@ class InvalidFacetFilterError(ApiException):
        """Initialize the exception.

        Args:
-            key: The unknown filter key provided by the caller
-            valid_keys: Set of valid keys derived from the declared facet_fields
+            key: The unknown filter key provided by the caller.
+            valid_keys: Set of valid keys derived from the declared facet_fields.
        """
        self.key = key
        self.valid_keys = valid_keys
-        detail = (
-            f"'{key}' is not a declared facet field. "
-            f"Valid keys: {sorted(valid_keys) or 'none — set facet_fields on the CRUD class'}."
+        super().__init__(
+            desc=(
+                f"'{key}' is not a declared facet field. "
+                f"Valid keys: {sorted(valid_keys) or 'none — set facet_fields on the CRUD class'}."
+            )
+        )
+
+
+class InvalidOrderFieldError(ApiException):
+    """Raised when order_by contains a field not in the allowed order fields."""
+
+    api_error = ApiError(
+        code=422,
+        msg="Invalid Order Field",
+        desc="The requested order field is not allowed for this resource.",
+        err_code="SORT-422",
+    )
+
+    def __init__(self, field: str, valid_fields: list[str]) -> None:
+        """Initialize the exception.
+
+        Args:
+            field: The unknown order field provided by the caller.
+            valid_fields: List of valid field names.
+        """
+        self.field = field
+        self.valid_fields = valid_fields
+        super().__init__(
+            desc=f"'{field}' is not an allowed order field. Valid fields: {valid_fields}."
        )
-        super().__init__(detail)


 def generate_error_responses(
@@ -133,44 +173,39 @@ def generate_error_responses(
 ) -> dict[int | str, dict[str, Any]]:
    """Generate OpenAPI response documentation for exceptions.

-    Use this to document possible error responses for an endpoint.
-
    Args:
-        *errors: Exception classes that inherit from ApiException
+        *errors: Exception classes that inherit from ApiException.

    Returns:
-        Dict suitable for FastAPI's responses parameter
-
-    Example:
-        ```python
-        from fastapi_toolsets.exceptions import generate_error_responses, UnauthorizedError, ForbiddenError
-
-        @app.get(
-            "/admin",
-            responses=generate_error_responses(UnauthorizedError, ForbiddenError)
-        )
-        async def admin_endpoint():
-            ...
-        ```
+        Dict suitable for FastAPI's ``responses`` parameter.
    """
    responses: dict[int | str, dict[str, Any]] = {}

    for error in errors:
        api_error = error.api_error
+        code = api_error.code

-        responses[api_error.code] = {
-            "model": ErrorResponse,
-            "description": api_error.msg,
-            "content": {
-                "application/json": {
-                    "example": {
-                        "data": api_error.data,
-                        "status": ResponseStatus.FAIL.value,
-                        "message": api_error.msg,
-                        "description": api_error.desc,
-                        "error_code": api_error.err_code,
+        if code not in responses:
+            responses[code] = {
+                "model": ErrorResponse,
+                "description": api_error.msg,
+                "content": {
+                    "application/json": {
+                        "examples": {},
                    }
-                }
+                },
+            }
+
+        responses[code]["content"]["application/json"]["examples"][
+            api_error.err_code
+        ] = {
+            "summary": api_error.msg,
+            "value": {
+                "data": api_error.data,
+                "status": ResponseStatus.FAIL.value,
+                "message": api_error.msg,
+                "description": api_error.desc,
+                "error_code": api_error.err_code,
            },
        }

@@ -1,10 +1,14 @@
 """Exception handlers for FastAPI applications."""

+from collections.abc import Callable
 from typing import Any

 from fastapi import FastAPI, Request, Response, status
-from fastapi.exceptions import RequestValidationError, ResponseValidationError
-from fastapi.openapi.utils import get_openapi
+from fastapi.exceptions import (
+    HTTPException,
+    RequestValidationError,
+    ResponseValidationError,
+)
 from fastapi.responses import JSONResponse

 from ..schemas import ErrorResponse, ResponseStatus
@@ -14,43 +18,20 @@ from .exceptions import ApiException
 def init_exceptions_handlers(app: FastAPI) -> FastAPI:
    """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.
-
    Args:
-        app: FastAPI application instance
+        app: FastAPI application instance.

    Returns:
-        The same FastAPI instance (for chaining)
-
-    Example:
-        ```python
-        from fastapi import FastAPI
-        from fastapi_toolsets.exceptions import init_exceptions_handlers
-
-        app = FastAPI()
-        init_exceptions_handlers(app)
-        ```
+        The same FastAPI instance (for chaining).
    """
    _register_exception_handlers(app)
-    app.openapi = lambda: _custom_openapi(app)  # type: ignore[method-assign]
+    _original_openapi = app.openapi
+    app.openapi = lambda: _patched_openapi(app, _original_openapi)  # type: ignore[method-assign]
    return app


 def _register_exception_handlers(app: FastAPI) -> None:
-    """Register all exception handlers on a FastAPI application.
-
-    Args:
-        app: FastAPI application instance
-
-    Example:
-        from fastapi import FastAPI
-        from fastapi_toolsets.exceptions import init_exceptions_handlers
-
-        app = FastAPI()
-        init_exceptions_handlers(app)
-    """
+    """Register all exception handlers on a FastAPI application."""

    @app.exception_handler(ApiException)
    async def api_exception_handler(request: Request, exc: ApiException) -> Response:
@@ -62,12 +43,25 @@ def _register_exception_handlers(app: FastAPI) -> None:
            description=api_error.desc,
            error_code=api_error.err_code,
        )
-
        return JSONResponse(
            status_code=api_error.code,
            content=error_response.model_dump(),
        )

+    @app.exception_handler(HTTPException)
+    async def http_exception_handler(request: Request, exc: HTTPException) -> Response:
+        """Handle Starlette/FastAPI HTTPException with a consistent error format."""
+        detail = exc.detail if isinstance(exc.detail, str) else "HTTP Error"
+        error_response = ErrorResponse(
+            message=detail,
+            error_code=f"HTTP-{exc.status_code}",
+        )
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=error_response.model_dump(),
+            headers=getattr(exc, "headers", None),
+        )
+
    @app.exception_handler(RequestValidationError)
    async def request_validation_handler(
        request: Request, exc: RequestValidationError
@@ -90,7 +84,6 @@ def _register_exception_handlers(app: FastAPI) -> None:
            description="An unexpected error occurred. Please try again later.",
            error_code="SERVER-500",
        )
-
        return JSONResponse(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            content=error_response.model_dump(),
@@ -105,11 +98,10 @@ def _format_validation_error(
    formatted_errors = []

    for error in errors:
-        field_path = ".".join(
-            str(loc)
-            for loc in error["loc"]
-            if loc not in ("body", "query", "path", "header", "cookie")
-        )
+        locs = error["loc"]
+        if locs and locs[0] in ("body", "query", "path", "header", "cookie"):
+            locs = locs[1:]
+        field_path = ".".join(str(loc) for loc in locs)
        formatted_errors.append(
            {
                "field": field_path or "root",
@@ -131,34 +123,22 @@ def _format_validation_error(
    )


-def _custom_openapi(app: FastAPI) -> dict[str, Any]:
-    """Generate custom OpenAPI schema with standardized error format.
-
-    Replaces default 422 validation error responses with the custom format.
+def _patched_openapi(
+    app: FastAPI, original_openapi: Callable[[], dict[str, Any]]
+) -> dict[str, Any]:
+    """Generate the OpenAPI schema and replace default 422 responses.

    Args:
-        app: FastAPI application instance
+        app: FastAPI application instance.
+        original_openapi: The previous ``app.openapi`` callable to delegate to.

    Returns:
-        OpenAPI schema dict
-
-    Example:
-        from fastapi import FastAPI
-        from fastapi_toolsets.exceptions import init_exceptions_handlers
-
-        app = FastAPI()
-        init_exceptions_handlers(app)  # Automatically sets custom OpenAPI
+        Patched OpenAPI schema dict.
    """
    if app.openapi_schema:
        return app.openapi_schema

-    openapi_schema = get_openapi(
-        title=app.title,
-        version=app.version,
-        openapi_version=app.openapi_version,
-        description=app.description,
-        routes=app.routes,
-    )
+    openapi_schema = original_openapi()

    for path_data in openapi_schema.get("paths", {}).values():
        for operation in path_data.values():
@@ -168,20 +148,25 @@ def _custom_openapi(app: FastAPI) -> dict[str, Any]:
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
-                                "example": {
-                                    "data": {
-                                        "errors": [
-                                            {
-                                                "field": "field_name",
-                                                "message": "value is not valid",
-                                                "type": "value_error",
-                                            }
-                                        ]
-                                    },
-                                    "status": ResponseStatus.FAIL.value,
-                                    "message": "Validation Error",
-                                    "description": "1 validation error(s) detected",
-                                    "error_code": "VAL-422",
+                                "examples": {
+                                    "VAL-422": {
+                                        "summary": "Validation Error",
+                                        "value": {
+                                            "data": {
+                                                "errors": [
+                                                    {
+                                                        "field": "field_name",
+                                                        "message": "value is not valid",
+                                                        "type": "value_error",
+                                                    }
+                                                ]
+                                            },
+                                            "status": ResponseStatus.FAIL.value,
+                                            "message": "Validation Error",
+                                            "description": "1 validation error(s) detected",
+                                            "error_code": "VAL-422",
+                                        },
+                                    }
                                }
                            }
                        },
@@ -1,9 +1,11 @@
 """Tests for CRUD search functionality."""

+import inspect
 import uuid

 import pytest
 from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.sql.elements import ColumnElement, UnaryExpression

 from fastapi_toolsets.crud import (
    CrudFactory,
@@ -11,6 +13,7 @@ from fastapi_toolsets.crud import (
    SearchConfig,
    get_searchable_fields,
 )
+from fastapi_toolsets.exceptions import InvalidOrderFieldError
 from fastapi_toolsets.schemas import OffsetPagination

 from .conftest import (
@@ -407,7 +410,7 @@ class TestNoSearchableFieldsError:
        from fastapi_toolsets.exceptions import NoSearchableFieldsError

        error = NoSearchableFieldsError(User)
-        assert "User" in str(error)
+        assert "User" in error.api_error.desc
        assert error.model is User

    def test_error_raised_when_no_fields(self):
@@ -431,7 +434,7 @@ class TestNoSearchableFieldsError:
            build_search_filters(NoStringModel, "test")

        assert exc_info.value.model is NoStringModel
-        assert "NoStringModel" in str(exc_info.value)
+        assert "NoStringModel" in exc_info.value.api_error.desc


 class TestGetSearchableFields:
@@ -1014,3 +1017,144 @@ class TestFilterParamsSchema:

        assert isinstance(result.pagination, OffsetPagination)
        assert result.pagination.total_count == 2
+
+
+class TestOrderParamsSchema:
+    """Tests for AsyncCrud.order_params()."""
+
+    def test_generates_order_by_and_order_params(self):
+        """Returned dependency has order_by and order query params."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username, User.email])
+        dep = UserOrderCrud.order_params()
+
+        param_names = set(inspect.signature(dep).parameters)
+        assert param_names == {"order_by", "order"}
+
+    def test_dependency_name_includes_model_name(self):
+        """Dependency function is named after the model."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params()
+        assert getattr(dep, "__name__") == "UserOrderParams"
+
+    def test_raises_when_no_order_fields(self):
+        """ValueError raised when no order_fields are configured or provided."""
+        with pytest.raises(ValueError, match="no order_fields"):
+            UserCrud.order_params()
+
+    def test_order_fields_override(self):
+        """order_fields= parameter overrides the class-level default."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username, User.email])
+        dep = UserOrderCrud.order_params(order_fields=[User.email])
+
+        param_names = set(inspect.signature(dep).parameters)
+        assert "order_by" in param_names
+        # description should only mention email, not username
+        sig = inspect.signature(dep)
+        description = sig.parameters["order_by"].default.description
+        assert "email" in description
+        assert "username" not in description
+
+    def test_order_by_description_lists_valid_fields(self):
+        """order_by query param description mentions each allowed field."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username, User.email])
+        dep = UserOrderCrud.order_params()
+
+        sig = inspect.signature(dep)
+        description = sig.parameters["order_by"].default.description
+        assert "username" in description
+        assert "email" in description
+
+    def test_default_order_reflected_in_order_default(self):
+        """default_order is used as the default value for order."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep_asc = UserOrderCrud.order_params(default_order="asc")
+        dep_desc = UserOrderCrud.order_params(default_order="desc")
+
+        sig_asc = inspect.signature(dep_asc)
+        sig_desc = inspect.signature(dep_desc)
+        assert sig_asc.parameters["order"].default.default == "asc"
+        assert sig_desc.parameters["order"].default.default == "desc"
+
+    @pytest.mark.anyio
+    async def test_no_order_by_no_default_returns_none(self):
+        """Returns None when order_by is absent and no default_field is set."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params()
+        result = await dep(order_by=None, order="asc")
+        assert result is None
+
+    @pytest.mark.anyio
+    async def test_no_order_by_with_default_field_returns_asc_expression(self):
+        """Returns default_field.asc() when order_by absent and order=asc."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params(default_field=User.username)
+        result = await dep(order_by=None, order="asc")
+        assert isinstance(result, UnaryExpression)
+        assert "ASC" in str(result)
+
+    @pytest.mark.anyio
+    async def test_no_order_by_with_default_field_returns_desc_expression(self):
+        """Returns default_field.desc() when order_by absent and order=desc."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params(default_field=User.username)
+        result = await dep(order_by=None, order="desc")
+        assert isinstance(result, UnaryExpression)
+        assert "DESC" in str(result)
+
+    @pytest.mark.anyio
+    async def test_valid_order_by_asc(self):
+        """Returns field.asc() for a valid order_by with order=asc."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params()
+        result = await dep(order_by="username", order="asc")
+        assert isinstance(result, UnaryExpression)
+        assert "ASC" in str(result)
+
+    @pytest.mark.anyio
+    async def test_valid_order_by_desc(self):
+        """Returns field.desc() for a valid order_by with order=desc."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params()
+        result = await dep(order_by="username", order="desc")
+        assert isinstance(result, UnaryExpression)
+        assert "DESC" in str(result)
+
+    @pytest.mark.anyio
+    async def test_invalid_order_by_raises_invalid_order_field_error(self):
+        """Raises InvalidOrderFieldError for an unknown order_by value."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        dep = UserOrderCrud.order_params()
+        with pytest.raises(InvalidOrderFieldError) as exc_info:
+            await dep(order_by="nonexistent", order="asc")
+        assert exc_info.value.field == "nonexistent"
+        assert "username" in exc_info.value.valid_fields
+
+    @pytest.mark.anyio
+    async def test_multiple_fields_all_resolve(self):
+        """All configured fields resolve correctly via order_by."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username, User.email])
+        dep = UserOrderCrud.order_params()
+        result_username = await dep(order_by="username", order="asc")
+        result_email = await dep(order_by="email", order="desc")
+        assert isinstance(result_username, ColumnElement)
+        assert isinstance(result_email, ColumnElement)
+
+    @pytest.mark.anyio
+    async def test_order_params_integrates_with_get_multi(
+        self, db_session: AsyncSession
+    ):
+        """order_params output is accepted by get_multi(order_by=...)."""
+        UserOrderCrud = CrudFactory(User, order_fields=[User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="charlie", email="c@test.com")
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        dep = UserOrderCrud.order_params()
+        order_by = await dep(order_by="username", order="asc")
+        results = await UserOrderCrud.get_multi(db_session, order_by=order_by)
+
+        assert results[0].username == "alice"
+        assert results[1].username == "charlie"
@@ -14,6 +14,7 @@ from fastapi_toolsets.db import (
    lock_tables,
    wait_for_row_change,
 )
+from fastapi_toolsets.exceptions import NotFoundError

 from .conftest import DATABASE_URL, Base, Role, RoleCrud, User

@@ -307,9 +308,9 @@ class TestWaitForRowChange:

    @pytest.mark.anyio
    async def test_nonexistent_row_raises(self, db_session: AsyncSession):
-        """Raises LookupError when the row does not exist."""
+        """Raises NotFoundError when the row does not exist."""
        fake_id = uuid.uuid4()
-        with pytest.raises(LookupError, match="not found"):
+        with pytest.raises(NotFoundError, match="not found"):
            await wait_for_row_change(db_session, Role, fake_id, interval=0.05)

    @pytest.mark.anyio
@@ -326,7 +327,7 @@ class TestWaitForRowChange:

    @pytest.mark.anyio
    async def test_deleted_row_raises(self, db_session: AsyncSession, engine):
-        """Raises LookupError when the row is deleted during polling."""
+        """Raises NotFoundError when the row is deleted during polling."""
        role = Role(name="delete_role")
        db_session.add(role)
        await db_session.commit()
@@ -340,6 +341,6 @@ class TestWaitForRowChange:
                await other.commit()

        delete_task = asyncio.create_task(delete_later())
-        with pytest.raises(LookupError):
+        with pytest.raises(NotFoundError):
            await wait_for_row_change(db_session, Role, role.id, interval=0.05)
        await delete_task
@@ -15,12 +15,14 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_asyn
 from docs_src.examples.pagination_search.db import get_db
 from docs_src.examples.pagination_search.models import Article, Base, Category
 from docs_src.examples.pagination_search.routes import router
+from fastapi_toolsets.exceptions import init_exceptions_handlers

 from .conftest import DATABASE_URL


 def build_app(session: AsyncSession) -> FastAPI:
    app = FastAPI()
+    init_exceptions_handlers(app)

    async def override_get_db():
        yield session
@@ -269,3 +271,125 @@ class TestCursorPagination:
        body = resp.json()
        assert len(body["data"]) == 1
        assert body["data"][0]["title"] == "SQLAlchemy async"
+
+
+class TestOffsetSorting:
+    """Tests for order_by / order query parameters on the offset endpoint."""
+
+    @pytest.mark.anyio
+    async def test_default_order_uses_created_at_asc(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """No order_by → default field (created_at) ASC."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset")
+
+        assert resp.status_code == 200
+        titles = [a["title"] for a in resp.json()["data"]]
+        assert titles == ["FastAPI tips", "SQLAlchemy async", "Draft notes"]
+
+    @pytest.mark.anyio
+    async def test_order_by_title_asc(self, client: AsyncClient, ex_db_session):
+        """order_by=title&order=asc returns alphabetical order."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset?order_by=title&order=asc")
+
+        assert resp.status_code == 200
+        titles = [a["title"] for a in resp.json()["data"]]
+        assert titles == ["Draft notes", "FastAPI tips", "SQLAlchemy async"]
+
+    @pytest.mark.anyio
+    async def test_order_by_title_desc(self, client: AsyncClient, ex_db_session):
+        """order_by=title&order=desc returns reverse alphabetical order."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset?order_by=title&order=desc")
+
+        assert resp.status_code == 200
+        titles = [a["title"] for a in resp.json()["data"]]
+        assert titles == ["SQLAlchemy async", "FastAPI tips", "Draft notes"]
+
+    @pytest.mark.anyio
+    async def test_order_by_created_at_desc(self, client: AsyncClient, ex_db_session):
+        """order_by=created_at&order=desc returns newest-first."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/offset?order_by=created_at&order=desc")
+
+        assert resp.status_code == 200
+        titles = [a["title"] for a in resp.json()["data"]]
+        assert titles == ["Draft notes", "SQLAlchemy async", "FastAPI tips"]
+
+    @pytest.mark.anyio
+    async def test_invalid_order_by_returns_422(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """Unknown order_by field returns 422 with SORT-422 error code."""
+        resp = await client.get("/articles/offset?order_by=nonexistent_field")
+
+        assert resp.status_code == 422
+        body = resp.json()
+        assert body["error_code"] == "SORT-422"
+        assert body["status"] == "FAIL"
+
+
+class TestCursorSorting:
+    """Tests for order_by / order query parameters on the cursor endpoint.
+
+    In cursor_paginate the cursor_column is always the primary sort; order_by
+    acts as a secondary tiebreaker. With the seeded articles (all having unique
+    created_at values) the overall ordering is always created_at ASC regardless
+    of the order_by value — only the valid/invalid field check and the response
+    shape are meaningful here.
+    """
+
+    @pytest.mark.anyio
+    async def test_default_order_uses_created_at_asc(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """No order_by → default field (created_at) ASC."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/cursor")
+
+        assert resp.status_code == 200
+        titles = [a["title"] for a in resp.json()["data"]]
+        assert titles == ["FastAPI tips", "SQLAlchemy async", "Draft notes"]
+
+    @pytest.mark.anyio
+    async def test_order_by_title_asc_accepted(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """order_by=title is a valid field — request succeeds and returns all articles."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/cursor?order_by=title&order=asc")
+
+        assert resp.status_code == 200
+        assert len(resp.json()["data"]) == 3
+
+    @pytest.mark.anyio
+    async def test_order_by_title_desc_accepted(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """order_by=title&order=desc is valid — request succeeds and returns all articles."""
+        await seed(ex_db_session)
+
+        resp = await client.get("/articles/cursor?order_by=title&order=desc")
+
+        assert resp.status_code == 200
+        assert len(resp.json()["data"]) == 3
+
+    @pytest.mark.anyio
+    async def test_invalid_order_by_returns_422(
+        self, client: AsyncClient, ex_db_session
+    ):
+        """Unknown order_by field returns 422 with SORT-422 error code."""
+        resp = await client.get("/articles/cursor?order_by=nonexistent_field")
+
+        assert resp.status_code == 422
+        body = resp.json()
+        assert body["error_code"] == "SORT-422"
+        assert body["status"] == "FAIL"
@@ -2,12 +2,14 @@

 import pytest
 from fastapi import FastAPI
+from fastapi.exceptions import HTTPException
 from fastapi.testclient import TestClient

 from fastapi_toolsets.exceptions import (
    ApiException,
    ConflictError,
    ForbiddenError,
+    InvalidOrderFieldError,
    NotFoundError,
    UnauthorizedError,
    generate_error_responses,
@@ -35,8 +37,8 @@ class TestApiException:
        assert error.api_error.msg == "I'm a teapot"
        assert str(error) == "I'm a teapot"

-    def test_custom_detail_message(self):
-        """Custom detail overrides default message."""
+    def test_detail_overrides_msg_and_str(self):
+        """detail sets both str(exc) and api_error.msg; class-level msg is unchanged."""

        class CustomError(ApiException):
            api_error = ApiError(
@@ -46,8 +48,172 @@ class TestApiException:
                err_code="BAD-400",
            )

-        error = CustomError("Custom message")
-        assert str(error) == "Custom message"
+        error = CustomError("Widget not found")
+        assert str(error) == "Widget not found"
+        assert error.api_error.msg == "Widget not found"
+        assert CustomError.api_error.msg == "Bad Request"  # class unchanged
+
+    def test_desc_override(self):
+        """desc kwarg overrides api_error.desc on the instance only."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        err = MyError(desc="Custom desc.")
+        assert err.api_error.desc == "Custom desc."
+        assert MyError.api_error.desc == "Default."  # class unchanged
+
+    def test_data_override(self):
+        """data kwarg sets api_error.data on the instance only."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        err = MyError(data={"key": "value"})
+        assert err.api_error.data == {"key": "value"}
+        assert MyError.api_error.data is None  # class unchanged
+
+    def test_desc_and_data_override(self):
+        """detail, desc and data can all be overridden together."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        err = MyError("custom msg", desc="New desc.", data={"x": 1})
+        assert str(err) == "custom msg"
+        assert err.api_error.msg == "custom msg"  # detail also updates msg
+        assert err.api_error.desc == "New desc."
+        assert err.api_error.data == {"x": 1}
+        assert err.api_error.code == 400  # other fields unchanged
+
+    def test_class_api_error_not_mutated_after_instance_override(self):
+        """Raising with desc/data does not mutate the class-level api_error."""
+
+        class MyError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+        MyError(desc="Changed", data={"x": 1})
+        assert MyError.api_error.desc == "Default."
+        assert MyError.api_error.data is None
+
+    def test_subclass_uses_super_with_desc_and_data(self):
+        """Subclasses can delegate detail/desc/data to super().__init__()."""
+
+        class BuildValidationError(ApiException):
+            api_error = ApiError(
+                code=422,
+                msg="Build Validation Error",
+                desc="The build configuration is invalid.",
+                err_code="BUILD-422",
+            )
+
+            def __init__(self, *errors: str) -> None:
+                super().__init__(
+                    f"{len(errors)} validation error(s)",
+                    desc=", ".join(errors),
+                    data={"errors": [{"message": e} for e in errors]},
+                )
+
+        err = BuildValidationError("Field A is required", "Field B is invalid")
+        assert str(err) == "2 validation error(s)"
+        assert err.api_error.msg == "2 validation error(s)"  # detail set msg
+        assert err.api_error.desc == "Field A is required, Field B is invalid"
+        assert err.api_error.data == {
+            "errors": [
+                {"message": "Field A is required"},
+                {"message": "Field B is invalid"},
+            ]
+        }
+        assert err.api_error.code == 422  # other fields unchanged
+
+    def test_detail_desc_data_in_http_response(self):
+        """detail/desc/data overrides all appear correctly in the FastAPI HTTP response."""
+
+        class DynamicError(ApiException):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Default.", err_code="ERR-400"
+            )
+
+            def __init__(self, message: str) -> None:
+                super().__init__(
+                    message,
+                    desc=f"Detail: {message}",
+                    data={"reason": message},
+                )
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/error")
+        async def raise_error():
+            raise DynamicError("something went wrong")
+
+        client = TestClient(app)
+        response = client.get("/error")
+
+        assert response.status_code == 400
+        body = response.json()
+        assert body["message"] == "something went wrong"
+        assert body["description"] == "Detail: something went wrong"
+        assert body["data"] == {"reason": "something went wrong"}
+
+
+class TestApiExceptionGuard:
+    """Tests for the __init_subclass__ api_error guard."""
+
+    def test_missing_api_error_raises_type_error(self):
+        """Defining a subclass without api_error raises TypeError at class creation time."""
+        with pytest.raises(
+            TypeError, match="must define an 'api_error' class attribute"
+        ):
+
+            class BrokenError(ApiException):
+                pass
+
+    def test_abstract_subclass_skips_guard(self):
+        """abstract=True allows intermediate base classes without api_error."""
+
+        class BaseGroupError(ApiException, abstract=True):
+            pass
+
+        # Concrete child must still define it
+        class ConcreteError(BaseGroupError):
+            api_error = ApiError(
+                code=400, msg="Error", desc="Desc.", err_code="ERR-400"
+            )
+
+        err = ConcreteError()
+        assert err.api_error.code == 400
+
+    def test_abstract_child_still_requires_api_error_on_concrete(self):
+        """Concrete subclass of an abstract class must define api_error."""
+
+        class Base(ApiException, abstract=True):
+            pass
+
+        with pytest.raises(
+            TypeError, match="must define an 'api_error' class attribute"
+        ):
+
+            class Concrete(Base):
+                pass
+
+    def test_inherited_api_error_satisfies_guard(self):
+        """Subclass that inherits api_error from a parent does not need its own."""
+
+        class ConcreteError(NotFoundError):
+            pass
+
+        err = ConcreteError()
+        assert err.api_error.code == 404


 class TestBuiltInExceptions:
@@ -89,7 +255,7 @@ class TestGenerateErrorResponses:
        assert responses[404]["description"] == "Not Found"

    def test_generates_multiple_responses(self):
-        """Generates responses for multiple exceptions."""
+        """Generates responses for multiple exceptions with distinct status codes."""
        responses = generate_error_responses(
            UnauthorizedError,
            ForbiddenError,
@@ -100,15 +266,24 @@ class TestGenerateErrorResponses:
        assert 403 in responses
        assert 404 in responses

-    def test_response_has_example(self):
-        """Generated response includes example."""
+    def test_response_has_named_example(self):
+        """Generated response uses named examples keyed by err_code."""
        responses = generate_error_responses(NotFoundError)
-        example = responses[404]["content"]["application/json"]["example"]
+        examples = responses[404]["content"]["application/json"]["examples"]

-        assert example["status"] == "FAIL"
-        assert example["error_code"] == "RES-404"
-        assert example["message"] == "Not Found"
-        assert example["data"] is None
+        assert "RES-404" in examples
+        value = examples["RES-404"]["value"]
+        assert value["status"] == "FAIL"
+        assert value["error_code"] == "RES-404"
+        assert value["message"] == "Not Found"
+        assert value["data"] is None
+
+    def test_response_example_has_summary(self):
+        """Each named example carries a summary equal to api_error.msg."""
+        responses = generate_error_responses(NotFoundError)
+        example = responses[404]["content"]["application/json"]["examples"]["RES-404"]
+
+        assert example["summary"] == "Not Found"

    def test_response_example_with_data(self):
        """Generated response includes data when set on ApiError."""
@@ -123,9 +298,49 @@ class TestGenerateErrorResponses:
            )

        responses = generate_error_responses(ErrorWithData)
-        example = responses[400]["content"]["application/json"]["example"]
+        value = responses[400]["content"]["application/json"]["examples"]["BAD-400"][
+            "value"
+        ]

-        assert example["data"] == {"details": "some context"}
+        assert value["data"] == {"details": "some context"}
+
+    def test_two_errors_same_code_both_present(self):
+        """Two exceptions with the same HTTP code produce two named examples."""
+
+        class BadRequestA(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad A", desc="Reason A.", err_code="ERR-A"
+            )
+
+        class BadRequestB(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad B", desc="Reason B.", err_code="ERR-B"
+            )
+
+        responses = generate_error_responses(BadRequestA, BadRequestB)
+
+        assert 400 in responses
+        examples = responses[400]["content"]["application/json"]["examples"]
+        assert "ERR-A" in examples
+        assert "ERR-B" in examples
+        assert examples["ERR-A"]["value"]["message"] == "Bad A"
+        assert examples["ERR-B"]["value"]["message"] == "Bad B"
+
+    def test_two_errors_same_code_single_top_level_entry(self):
+        """Two exceptions with the same HTTP code produce exactly one top-level entry."""
+
+        class BadRequestA(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad A", desc="Reason A.", err_code="ERR-A"
+            )
+
+        class BadRequestB(ApiException):
+            api_error = ApiError(
+                code=400, msg="Bad B", desc="Reason B.", err_code="ERR-B"
+            )
+
+        responses = generate_error_responses(BadRequestA, BadRequestB)
+        assert len([k for k in responses if k == 400]) == 1


 class TestInitExceptionsHandlers:
@@ -249,13 +464,68 @@ class TestInitExceptionsHandlers:
        assert data["status"] == "FAIL"
        assert data["error_code"] == "SERVER-500"

-    def test_custom_openapi_schema(self):
-        """Customizes OpenAPI schema for 422 responses."""
+    def test_handles_http_exception(self):
+        """Handles starlette HTTPException with consistent ErrorResponse envelope."""
        app = FastAPI()
        init_exceptions_handlers(app)

+        @app.get("/protected")
+        async def protected():
+            raise HTTPException(status_code=403, detail="Forbidden")
+
+        client = TestClient(app)
+        response = client.get("/protected")
+
+        assert response.status_code == 403
+        data = response.json()
+        assert data["status"] == "FAIL"
+        assert data["error_code"] == "HTTP-403"
+        assert data["message"] == "Forbidden"
+
+    def test_handles_http_exception_404_from_route(self):
+        """HTTPException(404) raised inside a route uses the consistent ErrorResponse envelope."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/items/{item_id}")
+        async def get_item(item_id: int):
+            raise HTTPException(status_code=404, detail="Item not found")
+
+        client = TestClient(app)
+        response = client.get("/items/99")
+
+        assert response.status_code == 404
+        data = response.json()
+        assert data["status"] == "FAIL"
+        assert data["error_code"] == "HTTP-404"
+        assert data["message"] == "Item not found"
+
+    def test_handles_http_exception_forwards_headers(self):
+        """HTTPException with WWW-Authenticate header forwards it in the response."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/secure")
+        async def secure():
+            raise HTTPException(
+                status_code=401,
+                detail="Not authenticated",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+        client = TestClient(app)
+        response = client.get("/secure")
+
+        assert response.status_code == 401
+        assert response.headers.get("www-authenticate") == "Bearer"
+
+    def test_custom_openapi_schema(self):
+        """Customises OpenAPI schema for 422 responses using named examples."""
        from pydantic import BaseModel

+        app = FastAPI()
+        init_exceptions_handlers(app)
+
        class Item(BaseModel):
            name: str

@@ -268,8 +538,128 @@ class TestInitExceptionsHandlers:
        post_op = openapi["paths"]["/items"]["post"]
        assert "422" in post_op["responses"]
        resp_422 = post_op["responses"]["422"]
-        example = resp_422["content"]["application/json"]["example"]
-        assert example["error_code"] == "VAL-422"
+        examples = resp_422["content"]["application/json"]["examples"]
+        assert "VAL-422" in examples
+        assert examples["VAL-422"]["value"]["error_code"] == "VAL-422"
+
+    def test_custom_openapi_preserves_app_metadata(self):
+        """_patched_openapi preserves custom FastAPI app-level metadata."""
+        app = FastAPI(
+            title="My API",
+            version="2.0.0",
+            description="Custom description",
+        )
+        init_exceptions_handlers(app)
+
+        schema = app.openapi()
+        assert schema["info"]["title"] == "My API"
+        assert schema["info"]["version"] == "2.0.0"
+
+    def test_handles_response_validation_error(self):
+        """Handles ResponseValidationError with a structured 422 response."""
+        from pydantic import BaseModel
+
+        class CountResponse(BaseModel):
+            count: int
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/broken", response_model=CountResponse)
+        async def broken():
+            return {"count": "not-a-number"}  # triggers ResponseValidationError
+
+        client = TestClient(app, raise_server_exceptions=False)
+        response = client.get("/broken")
+
+        assert response.status_code == 422
+        data = response.json()
+        assert data["status"] == "FAIL"
+        assert data["error_code"] == "VAL-422"
+        assert "errors" in data["data"]
+
+    def test_handles_validation_error_with_non_standard_loc(self):
+        """Validation error with empty loc tuple maps the field to 'root'."""
+        from fastapi.exceptions import RequestValidationError
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/root-error")
+        async def root_error():
+            raise RequestValidationError(
+                [
+                    {
+                        "type": "custom",
+                        "loc": (),
+                        "msg": "root level error",
+                        "input": None,
+                        "url": "",
+                    }
+                ]
+            )
+
+        client = TestClient(app)
+        response = client.get("/root-error")
+
+        assert response.status_code == 422
+        data = response.json()
+        assert data["data"]["errors"][0]["field"] == "root"
+
+    def test_openapi_schema_cached_after_first_call(self):
+        """app.openapi() returns the cached schema on subsequent calls."""
+        from pydantic import BaseModel
+
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        class Item(BaseModel):
+            name: str
+
+        @app.post("/items")
+        async def create_item(item: Item):
+            return item
+
+        schema_first = app.openapi()
+        schema_second = app.openapi()
+        assert schema_first is schema_second
+
+    def test_openapi_skips_operations_without_422(self):
+        """_patched_openapi leaves operations that have no 422 response unchanged."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/ping")
+        async def ping():
+            return {"ok": True}
+
+        schema = app.openapi()
+        get_op = schema["paths"]["/ping"]["get"]
+        assert "422" not in get_op["responses"]
+        assert "200" in get_op["responses"]
+
+    def test_openapi_skips_non_dict_path_item_values(self):
+        """_patched_openapi ignores non-dict values in path items (e.g. path-level parameters)."""
+        from fastapi_toolsets.exceptions.handler import _patched_openapi
+
+        app = FastAPI()
+
+        def fake_openapi() -> dict:
+            return {
+                "paths": {
+                    "/items": {
+                        "parameters": [
+                            {"name": "q", "in": "query"}
+                        ],  # list, not a dict
+                        "get": {"responses": {"200": {"description": "OK"}}},
+                    }
+                }
+            }
+
+        schema = _patched_openapi(app, fake_openapi)
+        # The list value was skipped without error; the GET operation is intact
+        assert schema["paths"]["/items"]["parameters"] == [{"name": "q", "in": "query"}]
+        assert "422" not in schema["paths"]["/items"]["get"]["responses"]


 class TestExceptionIntegration:
@@ -334,3 +724,43 @@ class TestExceptionIntegration:

        assert response.status_code == 200
        assert response.json() == {"id": 1}
+
+
+class TestInvalidOrderFieldError:
+    """Tests for InvalidOrderFieldError exception."""
+
+    def test_api_error_attributes(self):
+        """InvalidOrderFieldError has correct api_error metadata."""
+        assert InvalidOrderFieldError.api_error.code == 422
+        assert InvalidOrderFieldError.api_error.err_code == "SORT-422"
+        assert InvalidOrderFieldError.api_error.msg == "Invalid Order Field"
+
+    def test_stores_field_and_valid_fields(self):
+        """InvalidOrderFieldError stores field and valid_fields on the instance."""
+        error = InvalidOrderFieldError("unknown", ["name", "created_at"])
+        assert error.field == "unknown"
+        assert error.valid_fields == ["name", "created_at"]
+
+    def test_description_contains_field_and_valid_fields(self):
+        """api_error.desc mentions the bad field and valid options."""
+        error = InvalidOrderFieldError("bad_field", ["name", "email"])
+        assert "bad_field" in error.api_error.desc
+        assert "name" in error.api_error.desc
+        assert "email" in error.api_error.desc
+
+    def test_handled_as_422_by_exception_handler(self):
+        """init_exceptions_handlers turns InvalidOrderFieldError into a 422 response."""
+        app = FastAPI()
+        init_exceptions_handlers(app)
+
+        @app.get("/items")
+        async def list_items():
+            raise InvalidOrderFieldError("bad", ["name"])
+
+        client = TestClient(app)
+        response = client.get("/items")
+
+        assert response.status_code == 422
+        data = response.json()
+        assert data["error_code"] == "SORT-422"
+        assert data["status"] == "FAIL"
@@ -251,7 +251,7 @@ wheels = [

 [[package]]
 name = "fastapi-toolsets"
-version = "1.2.1"
+version = "1.3.0"
 source = { editable = "." }
 dependencies = [
    { name = "asyncpg" },
Author	SHA1	Message	Date
d3vyceandGitHub	05b5a2c876	feat: rework Exception/ApiError (#107 ) * feat: rework Exception/ApiError * docs: update exceptions module * fix: docstring	2026-03-02 16:34:29 +01:00
d3vyceandGitHub	4a020c56d1	feat: Raise NotFoundError instead of LookupError in wait_for_row_change (#105 )	2026-03-02 14:28:37 +01:00
d3vyce	56d365d14b	Version 1.3.0	2026-03-01 05:22:16 -05:00
d3vyceandGitHub	a257d85d45	Add sort_params helper in CrudFactory (#103 ) * feat: add sort_params helper in CrudFactory * docs: add sorting * fix: change sort_by to order_by	2026-03-01 11:20:43 +01:00