Error Taxonomy

Error Taxonomy - Structured Error Classification

Unified error classification system ensuring every error in the stack has a code, category, severity, and user-facing message. Bridges the FastAPI ErrorResponse model with the Next.js ApiClientError class.

Description

Provides a structured error code taxonomy following the DOMAIN_CATEGORY_SPECIFIC format. Maps every runtime error to an HTTP status code, severity level, and user-facing message, ensuring consistent error handling between the FastAPI backend and Next.js frontend.

When to Apply

Positive Triggers

• Creating or modifying API error responses
• Adding new HTTPException raises in FastAPI routes
• Implementing frontend error handling or display
• Designing error boundaries for React components
• Reviewing error consistency across backend and frontend
• User mentions: "error handling", "error codes", "error messages", "error response"

Negative Triggers

• Implementing retry/resilience logic (use retry-strategy instead)
• Designing React error boundary components (use error-boundary instead)
• The error is a build/lint/type error (not runtime error handling)

Core Directives

Error Code Format

All error codes follow the pattern: {DOMAIN}_{CATEGORY}_{SPECIFIC}

AUTH_VALIDATION_INVALID_TOKEN
AGENT_RUNTIME_TIMEOUT
DATA_VALIDATION_MISSING_FIELD

Domains

Categories

Severity Levels

---

Backend Pattern (FastAPI)

Standard Error Response Model

The project already has ErrorResponse in apps/backend/src/models/contractor.py. Extend this as the canonical model:

from pydantic import BaseModel, Field
from typing import Optional
from enum import Enum


class ErrorSeverity(str, Enum):
    FATAL = "fatal"
    ERROR = "error"
    WARNING = "warning"


class ErrorResponse(BaseModel):
    """Canonical error response for all API endpoints."""

    detail: str = Field(..., description="Human-readable error message")
    error_code: str = Field(..., description="Machine-readable error code")
    severity: ErrorSeverity = Field(
        default=ErrorSeverity.ERROR,
        description="Error severity level"
    )
    field: Optional[str] = Field(
        None,
        description="Specific field that caused the error (validation)"
    )

Raising Errors

# GOOD: Structured error with code
raise HTTPException(
    status_code=status.HTTP_401_UNAUTHORIZED,
    detail=ErrorResponse(
        detail="Token has expired. Please log in again.",
        error_code="AUTH_VALIDATION_EXPIRED_TOKEN",
    ).model_dump(),
)

# BAD: Unstructured string
raise HTTPException(
    status_code=401,
    detail="Invalid token",
)

Validation Error Handler

Register a global handler to convert Pydantic ValidationError into structured responses:

from fastapi import Request
from fastapi.responses import JSONResponse
from pydantic import ValidationError


async def validation_exception_handler(
    request: Request,
    exc: ValidationError
) -> JSONResponse:
    errors = []
    for error in exc.errors():
        field = ".".join(str(loc) for loc in error["loc"])
        errors.append({
            "detail": error["msg"],
            "error_code": f"DATA_VALIDATION_{error['type'].upper()}",
            "field": field,
        })
    return JSONResponse(
        status_code=422,
        content={"errors": errors},
    )

---

Frontend Pattern (Next.js)

Error Interface

The project has ApiError and ApiClientError in apps/web/lib/api/client.ts. Extend to include severity:

export interface ApiError {
  detail: string;
  error_code: string;
  severity?: 'fatal' | 'error' | 'warning';
  field?: string;
}

export class ApiClientError extends Error {
  constructor(
    message: string,
    public status: number,
    public errorCode: string,
    public severity: 'fatal' | 'error' | 'warning' = 'error',
    public field?: string
  ) {
    super(message);
    this.name = 'ApiClientError';
  }

  get isAuth(): boolean {
    return this.errorCode.startsWith('AUTH_');
  }

  get isValidation(): boolean {
    return this.errorCode.includes('_VALIDATION_');
  }

  get isRetryable(): boolean {
    return this.status === 429 || this.status >= 500;
  }
}

User-Facing Message Map

Map technical error codes to user-friendly messages:

const ERROR_MESSAGES: Record<string, string> = {
  AUTH_VALIDATION_INVALID_TOKEN: 'Your session has expired. Please sign in again.',
  AUTH_VALIDATION_EXPIRED_TOKEN: 'Your session has expired. Please sign in again.',
  AUTH_PERMISSION_DENIED: 'You do not have permission to perform this action.',
  AUTH_PERMISSION_INACTIVE: 'Your account has been deactivated.',
  DATA_VALIDATION_MISSING_FIELD: 'Please fill in all required fields.',
  AGENT_RUNTIME_TIMEOUT: 'The AI agent took too long to respond. Please try again.',
  AGENT_EXTERNAL_PROVIDER_DOWN: 'The AI service is temporarily unavailable.',
  SYS_EXTERNAL_DATABASE: 'A database error occurred. Please try again later.',
  SYS_RATELIMIT_EXCEEDED: 'Too many requests. Please wait a moment.',
};

export function getUserMessage(error: ApiClientError): string {
  return ERROR_MESSAGES[error.errorCode] ?? error.message;
}

---

Error Code Registry

Authentication Errors

Agent Errors

Data Errors

System Errors

---

Adding New Error Codes

When adding a new error code:

1. Choose domain from the Domains table 2. Choose category from the Categories table 3. Add specific identifier describing the failure 4. Register in the Error Code Registry table above 5. Map a user-facing message in the frontend ERROR_MESSAGES 6. Use the ErrorResponse model when raising HTTPException

Anti-Patterns

Checklist

• [ ] Error codes follow DOMAIN_CATEGORY_SPECIFIC format
• [ ] User-facing messages defined in frontend ERROR_MESSAGES map
• [ ] HTTP status codes mapped correctly per severity table
• [ ] Frontend ApiClientError handling matches backend ErrorResponse contract
• [ ] New error codes registered in the Error Code Registry section

Response Format

[AGENT_ACTIVATED]: Error Taxonomy
[PHASE]: {Classification | Implementation | Review}
[STATUS]: {in_progress | complete}

{error analysis or implementation guidance}

[NEXT_ACTION]: {what to do next}

Integration Points

Council of Logic (Shannon Check)

• Error messages must be concise — no verbose stack traces in user-facing output
• Error codes encode maximum information in minimum characters
• One error code per failure mode, no duplicates

API Contract

• Every API endpoint must document its possible error codes
• Error codes form part of the API contract between backend and frontend
• Breaking error code changes require a version bump

Australian Localisation (en-AU)

• Date Format: DD/MM/YYYY
• Currency: AUD ($)
• Spelling: colour, behaviour, optimisation, analyse, centre, authorisation
• Tone: Direct, professional — error messages should be helpful, not apologetic