This Claude skill provides a standardized framework for implementing exception handling in FastAPI applications using the RFC 9457 (Problem Details for HTTP APIs) specification. It streamlines the creation of resource-specific errors, ensures consistent machine-readable responses, and automates the conversion of Python exceptions into structured JSON or CBOR error payloads, significantly improving API reliability and developer experience.

When should I use exceptions?

exceptions is useful in the following scenarios: • Standardizing API error responses across microservices to ensure consistent error handling for frontend and mobile clients. • Implementing domain-specific exceptions (e.g., ResourceNotFoundError, ConflictError) that automatically map to correct HTTP status codes like 404 or 409. • Enhancing API observability by automatically attaching X-Request-ID and schema metadata to every error response for easier debugging. • Decoupling business logic from the transport layer by raising standardized exceptions in services that are automatically caught and formatted by the API router. • Ensuring production security by automatically stripping sensitive internal error details from 5xx server responses while maintaining detailed logs.

name	exceptions
description	Guide for creating exceptions using fastapi-problem that are automatically converted to RFC 9457 Problem Details responses.

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

exceptions

When & Why to Use This Skill

Use Cases