Exception Taxonomy
Hierarchical exception system with HTTP status codes, error codes, and structured responses for consistent API error handling.
When to Use This Skill
- Building APIs that need consistent error responses
- Creating machine-readable error codes for client handling
- Implementing retry logic based on error types
- Standardizing error handling across a large codebase
Core Concepts
A well-designed exception taxonomy provides:
- Consistent error responses across all endpoints
- Machine-readable error codes for client handling
- Human-readable messages for debugging
- HTTP status code mapping
- Retry hints for transient failures
The hierarchy typically follows:
BaseAppError (abstract)
├── AuthenticationError (401)
├── AuthorizationError (403)
├── ResourceError (404/409)
├── ValidationError (422)
├── RateLimitError (429)
├── ExternalServiceError (502/503)
└── PaymentError (402)Implementation
Python
from dataclasses import dataclass, field
from typing import Optional, Dict, Any
from enum import Enum
class ErrorCode(str, Enum):
"""Standardized error codes for API responses."""
# Authentication
AUTH_INVALID_CREDENTIALS = "AUTH_INVALID_CREDENTIALS"
AUTH_TOKEN_EXPIRED = "AUTH_TOKEN_EXPIRED"
AUTH_TOKEN_INVALID = "AUTH_TOKEN_INVALID"
AUTH_EMAIL_EXISTS = "AUTH_EMAIL_EXISTS"
# Authorization
FORBIDDEN = "FORBIDDEN"
# Resources
RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND"
RESOURCE_CONFLICT = "RESOURCE_CONFLICT"
# Rate Limiting
RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
# External Services
GENERATION_FAILED = "GENERATION_FAILED"
GENERATION_TIMEOUT = "GENERATION_TIMEOUT"
# Validation
VALIDATION_ERROR = "VALIDATION_ERROR"
INVALID_STATE_TRANSITION = "INVALID_STATE_TRANSITION"
@dataclass
class BaseAppError(Exception):
"""Base exception for all application errors."""
message: str
code: ErrorCode
status_code: int = 500
details: Optional[Dict[str, Any]] = field(default_factory=dict)
retry_after: Optional[int] = None
def __post_init__(self):
super().__init__(self.message)
def to_dict(self) -> Dict[str, Any]:
"""Convert to API response format."""
error_dict = {
"error": {
"message": self.message,
"code": self.code.value,
}
}
if self.details:
error_dict["error"]["details"] = self.details
if self.retry_after is not None:
error_dict["error"]["retry_after"] = self.retry_after
return error_dict
@dataclass
class NotFoundError(BaseAppError):
"""Resource not found error."""
resource_type: str = "resource"
resource_id: str = ""
message: str = field(init=False)
code: ErrorCode = field(default=ErrorCode.RESOURCE_NOT_FOUND)
status_code: int = 404
def __post_init__(self):
self.message = f"{self.resource_type.title()} not found"
self.details = {
"resource_type": self.resource_type,
"resource_id": self.resource_id,
}
super().__post_init__()
@dataclass
class RateLimitError(BaseAppError):
"""Rate limit exceeded error."""
retry_after: int = 60
message: str = "Rate limit exceeded"
code: ErrorCode = field(default=ErrorCode.RATE_LIMIT_EXCEEDED)
status_code: int = 429
def __post_init__(self):
self.details = {"retry_after": self.retry_after}
super().__post_init__()
@dataclass
class InvalidStateTransitionError(BaseAppError):
"""Invalid state transition error."""
current_status: str = ""
target_status: str = ""
message: str = field(init=False)
code: ErrorCode = field(default=ErrorCode.INVALID_STATE_TRANSITION)
status_code: int = 409
def __post_init__(self):
self.message = f"Cannot transition from '{self.current_status}' to '{self.target_status}'"
self.details = {
"current_status": self.current_status,
"target_status": self.target_status,
}
super().__post_init__()TypeScript
export enum ErrorCode {
AUTH_INVALID_CREDENTIALS = 'AUTH_INVALID_CREDENTIALS',
AUTH_TOKEN_EXPIRED = 'AUTH_TOKEN_EXPIRED',
AUTH_TOKEN_INVALID = 'AUTH_TOKEN_INVALID',
FORBIDDEN = 'FORBIDDEN',
RESOURCE_NOT_FOUND = 'RESOURCE_NOT_FOUND',
RESOURCE_CONFLICT = 'RESOURCE_CONFLICT',
RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',
VALIDATION_ERROR = 'VALIDATION_ERROR',
INVALID_STATE_TRANSITION = 'INVALID_STATE_TRANSITION',
}
interface ErrorDetails {
[key: string]: unknown;
}
export class BaseAppError extends Error {
constructor(
public readonly message: string,
public readonly code: ErrorCode,
public readonly statusCode: number = 500,
public readonly details: ErrorDetails = {},
public readonly retryAfter?: number
) {
super(message);
this.name = this.constructor.name;
}
toJSON() {
const error: Record<string, unknown> = {
message: this.message,
code: this.code,
};
if (Object.keys(this.details).length > 0) {
error.details = this.details;
}
if (this.retryAfter !== undefined) {
error.retry_after = this.retryAfter;
}
return { error };
}
}
export class NotFoundError extends BaseAppError {
constructor(resourceType: string, resourceId: string) {
super(
`${resourceType.charAt(0).toUpperCase() + resourceType.slice(1)} not found`,
ErrorCode.RESOURCE_NOT_FOUND,
404,
{ resource_type: resourceType, resource_id: resourceId }
);
}
}
export class RateLimitError extends BaseAppError {
constructor(retryAfter: number = 60) {
super(
'Rate limit exceeded',
ErrorCode.RATE_LIMIT_EXCEEDED,
429,
{ retry_after: retryAfter },
retryAfter
);
}
}
export class InvalidStateTransitionError extends BaseAppError {
constructor(currentStatus: string, targetStatus: string) {
super(
`Cannot transition from '${currentStatus}' to '${targetStatus}'`,
ErrorCode.INVALID_STATE_TRANSITION,
409,
{ current_status: currentStatus, target_status: targetStatus }
);
}
}Usage Examples
FastAPI Exception Handlers
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
app = FastAPI()
@app.exception_handler(BaseAppError)
async def app_error_handler(request: Request, exc: BaseAppError) -> JSONResponse:
headers = {"Retry-After": str(exc.retry_after)} if exc.retry_after else None
return JSONResponse(
status_code=exc.status_code,
content=exc.to_dict(),
headers=headers,
)
@app.exception_handler(Exception)
async def generic_error_handler(request: Request, exc: Exception) -> JSONResponse:
logger.exception(f"Unexpected error: {exc}")
return JSONResponse(
status_code=500,
content={"error": {"message": "An unexpected error occurred", "code": "INTERNAL_ERROR"}},
)Route Usage
@router.get("/jobs/{job_id}")
async def get_job(job_id: str, user_id: str = Depends(get_current_user)):
job = await job_service.get(job_id)
if not job:
raise NotFoundError(resource_type="job", resource_id=job_id)
if job.user_id != user_id:
raise AuthorizationError(resource_type="job")
return jobClient-Side Handling (TypeScript)
interface APIError {
error: {
message: string;
code: string;
details?: Record<string, unknown>;
retry_after?: number;
};
}
function handleAPIError(error: APIError): void {
switch (error.error.code) {
case 'AUTH_TOKEN_EXPIRED':
authStore.refreshToken();
break;
case 'RATE_LIMIT_EXCEEDED':
const retryAfter = error.error.retry_after || 60;
toast.error(`Rate limited. Try again in ${retryAfter}s`);
break;
default:
toast.error(error.error.message);
}
}Best Practices
- Use specific exceptions - Create domain-specific exceptions rather than generic ones
- Include context - Always include relevant IDs and state in error details
- Map to HTTP codes - Each exception should have a clear HTTP status code
- Provide retry hints - For transient failures, include
retry_after - Use error codes - Machine-readable codes enable client-side handling logic
- Log appropriately - Log full details server-side, return safe messages to clients
Common Mistakes
- Using generic exceptions instead of domain-specific ones
- Forgetting to include resource IDs in error details
- Not providing retry hints for rate limit errors
- Exposing internal error details in production responses
- Inconsistent error response formats across endpoints
Related Patterns
- error-sanitization - Sanitize errors before returning to users
- error-handling - General error handling patterns
- rate-limiting - Rate limiting implementation