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 in the repository root.

Base Exception Classes

The project uses fastapi-problem base classes from app/exceptions/base.py:

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

| Base Class | Status Code | Use Case | |------------|-------------|----------| | NotFoundProblem | 404 | Resource not found | | ConflictProblem | 409 | Duplicate resource, state conflict | | BadRequestProblem | 400 | Invalid request (cursor, parameter) | | ForbiddenProblem | 403 | Access denied | | UnauthorisedProblem | 401 | Authentication required | | UnprocessableProblem | 422 | Validation failure | | ServerProblem | 500 | Internal server error |

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 suffix:

• {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