exception-taxonomy

name	exception-taxonomy
description	Hierarchical exception system with HTTP status codes, machine-readable error codes, and structured responses for consistent API error handling across all endpoints.
license	MIT
compatibility	TypeScript/JavaScript, Python
metadata	{"category":"errors","time":"3h","source":"drift-masterguide"}

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=)
    retry_after: [] = 
    
     ():
        ().__init__(.message)
    
     () -> [, ]:
        
        error_dict = {
            : {
                : .message,
                : .code.value,
            }
        }
         .details:
            error_dict[][] = .details
         .retry_after   :
            error_dict[][] = .retry_after
         error_dict



 ():
    
    resource_type:  = 
    resource_id:  = 
    message:  = field(init=)
    code: ErrorCode = field(default=ErrorCode.RESOURCE_NOT_FOUND)
    status_code:  = 
    
     ():
        .message = 
        .details = {
            : .resource_type,
            : .resource_id,
        }
        ().__post_init__()



 ():
    
    retry_after:  = 
    message:  = 
    code: ErrorCode = field(default=ErrorCode.RATE_LIMIT_EXCEEDED)
    status_code:  = 
    
     ():
        .details = {: .retry_after}
        ().__post_init__()



 ():
    
    current_status:  = 
    target_status:  = 
    message:  = field(init=)
    code: ErrorCode = field(default=ErrorCode.INVALID_STATE_TRANSITION)
    status_code:  = 
    
     ():
        .message = 
        .details = {
            : .current_status,
            : .target_status,
        }
        ().__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:  = {},
      ?: 
  ) {
    (message);
    . = ..;
  }

  () {
     : <, > = {
      : .,
      : .,
    };
     (.(.). > ) {
      error. = .;
    }
     (. !== ) {
      error. = .;
    }
     { error };
  }
}

     {
  () {
    (
      ,
      .,
      ,
      { : resourceType, : resourceId }
    );
  }
}

     {
  () {
    (
      ,
      .,
      ,
      { : retryAfter },
      retryAfter
    );
  }
}

     {
  () {
    (
      ,
      .,
      ,
      { : currentStatus, : 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 job

Client-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

1. Use specific exceptions - Create domain-specific exceptions rather than generic ones
2. Include context - Always include relevant IDs and state in error details
3. Map to HTTP codes - Each exception should have a clear HTTP status code
4. Provide retry hints - For transient failures, include retry_after
5. Use error codes - Machine-readable codes enable client-side handling logic
6. 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