Agent skill
exceptions
Guide for creating exceptions using fastapi-problem that are automatically converted to RFC 9457 Problem Details responses.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/exceptions
SKILL.md
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-problemsingletonehwith pre/post hooks - Adds
X-Request-IDto all error responses - Adds
$schemafield andLinkheader withrel="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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?