error-taxonomy

name	error-taxonomy
description	Structured error codes, categories, and user-facing messages for consistent error handling across FastAPI backend and Next.js frontend. Enforces a unified error contract between API responses and client-side handling.
license	MIT
metadata	{"author":"NodeJS-Starter-V1","version":"1.0.0","locale":"en-AU"}

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 instead)