fastapi-errors

fastapi-errors

Defines a simple, consistent error architecture for FastAPI backend services.

This skill standardizes the flow:

service/domain failure
→ application exception
→ global FastAPI exception handler
→ consistent JSON response

The goal is to prevent common FastAPI problems:

• HTTPException raised deep in service logic
• inconsistent error response formats
• duplicated status code logic
• domain failures implemented with builtin exceptions
• unexpected exceptions leaking poor diagnostics

---

Apply this Skill When

Apply when the user:

• asks how to structure FastAPI error handling
• is adding domain exceptions
• is designing service-layer failures
• is implementing API error responses
• is building a new FastAPI service
• is adding new domain errors in an existing repo

Do not apply when:

• the task is unrelated to application error handling
• the user explicitly wants a different architecture

---

Base Exception

The fastapi-init skill scaffolds a minimal version of this class. This skill defines the complete pattern. If both are present, this skill's version is authoritative.

The service defines one base exception for intentional application failures.

Preferred naming pattern:

<PackageName>Error

Examples:

BillingError
UserServiceError
InventoryError

If the package name cannot be determined, use:

AppError

Define all exceptions in a single module. In fastapi-init projects this is core/exceptions.py. In other layouts, exceptions.py at the package root is typical. Do not scatter them across feature files.

Example base implementation:

class AppError(Exception):
    status_code = 500
    detail: str = "An unexpected error occurred."

    def __init__(self, detail: str | None = None, status_code: int | None = None, **context):
        self.detail = detail if detail is not None else self.__class__.detail
        self.status_code = status_code if status_code is not None else self.__class__.status_code
        self.context = context
        super().__init__(self.detail)

    def __str__(self) -> str:
        return self.detail