Exception Creation

Use this skill when creating exceptions that are automatically converted to RFC 9457 Problem Details responses.

For comprehensive coding guidelines, see

AGENTS.md

Base Exception Classes

The project uses

fastapi-problem

app/exceptions/base.py

from fastapi_problem.error import (
    BadRequestProblem,
    ConflictProblem,
    ForbiddenProblem,
    NotFoundProblem,
    ServerProblem,
    UnauthorisedProblem,
    UnprocessableProblem,
)

NotFoundProblem

ConflictProblem

BadRequestProblem

ForbiddenProblem

UnauthorisedProblem

UnprocessableProblem

ServerProblem

Creating Resource-Specific Exceptions

Create new exceptions in

app/exceptions/

# app/exceptions/resource.py
"""
Resource-related exceptions.
"""

from fastapi_problem.error import ConflictProblem, NotFoundProblem


class ResourceNotFoundError(NotFoundProblem):
    """
    Raised when a resource cannot be found.
    """

    title = "Resource not found"


class ResourceAlreadyExistsError(ConflictProblem):
    """
    Raised when attempting to create a duplicate resource.
    """

    title = "Resource already exists"

Exporting Exceptions

Export new exceptions from

app/exceptions/__init__.py

from app.exceptions.base import (
    BadRequestProblem,
    ConflictProblem,
    ForbiddenProblem,
    NotFoundProblem,
    ServerProblem,
    UnauthorisedProblem,
    UnprocessableProblem,
)
from app.exceptions.resource import ResourceAlreadyExistsError, ResourceNotFoundError

__all__ = [
    "BadRequestProblem",
    "ConflictProblem",
    "ForbiddenProblem",
    "NotFoundProblem",
    "ResourceAlreadyExistsError",
    "ResourceNotFoundError",
    "ServerProblem",
    "UnauthorisedProblem",
    "UnprocessableProblem",
]

Using Exceptions

Import from the package root:

# In routers and services
from app.exceptions import ResourceNotFoundError, ResourceAlreadyExistsError

Raise exceptions in services:

async def get_resource(self, user_id: str) -> Resource:
    snapshot = await doc_ref.get()
    if not snapshot.exists:
        raise ResourceNotFoundError("Resource not found")
    return Resource(**snapshot.to_dict())

Exception Handling in Routers

Re-raise exceptions to let handlers convert them:

@router.get("/")
async def get_resource(
    current_user: CurrentUser,
    service: ResourceServiceDep,
) -> Resource:
    try:
        return await service.get_resource(current_user.uid)
    except (HTTPException, ResourceNotFoundError):
        raise
    except Exception:
        logger.exception("Error getting resource", extra={"user_id": current_user.uid})
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to retrieve resource"
        ) from None

RFC 9457 Problem Details Response

Exceptions are automatically converted to Problem Details format:

{
  "type": "about:blank",
  "title": "Resource not found",
  "status": 404,
  "detail": "Resource not found"
}

The exception handler in

app/core/exception_handler.py

• Uses

  fastapi-problem

  singleton

  eh

  with pre/post hooks
• Adds

  X-Request-ID

  to all error responses
• Adds

  $schema

  field and

  Link

  header with

  rel="describedBy"

  to error responses
• Supports CBOR error responses via

  CBORProblemPostHook

• Strips extras from 5xx errors in production via

  StripExtrasPostHook

Custom Detail Message

Pass a custom message when raising:

raise ResourceNotFoundError(detail="Resource with ID 'abc123' was not found")

Naming Convention

Use descriptive names with

Error

• {Resource}NotFoundError

• {Resource}AlreadyExistsError

• {Resource}InvalidError

• {Resource}ExpiredError

Testing

Test exception behavior:

def test_returns_404_when_not_found(
    client: TestClient,
    with_fake_user: None,
    mock_resource_service: AsyncMock,
) -> None:
    mock_resource_service.get_resource.side_effect = ResourceNotFoundError()

    response = client.get("/v1/resource")

    assert response.status_code == 404
    body = response.json()
    assert body["title"] == "Resource not found"
    assert body["status"] == 404