Menü
>-
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
npx skills add https://github.com/CleanExpo/ATO --skill error-taxonomyDer Befehl bleibt in einer Zeile. Scrollen Sie horizontal, um ihn vor dem Kopieren vollständig zu prüfen.
Sie bevorzugen eine lokale Kopie? Laden Sie die Dateien herunter, die SkillsMP derzeit vorliegen.
SKILL.md wird angezeigt
Basierend auf der SOC-Berufsklassifikation
| id | error-taxonomy |
| name | error-taxonomy |
| type | skill |
| version | 1.0.0 |
| created | 20/03/2026 |
| modified | 20/03/2026 |
| status | active |
| metadata | {"author":"NodeJS-Starter-V1","version":"1.0.0","locale":"en-AU"} |
| description | >- |
| context | fork |
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.
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.
HTTPException raises in FastAPI routesretry-strategy instead)error-boundary instead)All error codes follow the pattern: {DOMAIN}_{CATEGORY}_{SPECIFIC}
AUTH_VALIDATION_INVALID_TOKEN
AGENT_RUNTIME_TIMEOUT
DATA_VALIDATION_MISSING_FIELD
| Domain | Prefix | Scope |
|---|---|---|
| Authentication | AUTH_ | Login, JWT, permissions |
| Agent | AGENT_ | AI agent execution, LLM providers |
| Data | DATA_ | Validation, transformation, storage |
| Workflow | WORKFLOW_ | Pipeline, state machine, scheduling |
| System | SYS_ | Infrastructure, database, external services |
| Category |
|---|
| Suffix |
|---|
| Meaning |
|---|
| Validation | _VALIDATION_ | Input/schema validation failure |
| Runtime | _RUNTIME_ | Unexpected runtime failure |
| Permission | _PERMISSION_ | Authorisation or access denied |
| NotFound | _NOTFOUND_ | Resource does not exist |
| Conflict | _CONFLICT_ | State conflict or duplicate |
| RateLimit | _RATELIMIT_ | Throttled request |
| External | _EXTERNAL_ | Third-party service failure |
| Level | HTTP Range | Action |
|---|---|---|
| Fatal | 500-599 | Log + alert + escalate |
| Error | 400-499 | Log + return user message |
| Warning | 200 with warning header | Log only |
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)"
)
# 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",
)
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},
)
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;
}
}
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;
}
| Code | HTTP | Message |
|---|---|---|
AUTH_VALIDATION_INVALID_TOKEN | 401 | Invalid authentication token |
AUTH_VALIDATION_EXPIRED_TOKEN | 401 | Token has expired |
AUTH_VALIDATION_MISSING_TOKEN | 401 | No authentication token provided |
AUTH_PERMISSION_DENIED | 403 | Insufficient permissions |
AUTH_PERMISSION_INACTIVE | 403 | Account is inactive |
AUTH_PERMISSION_NOT_ADMIN | 403 | Admin access required |
AUTH_NOTFOUND_USER | 404 | User not found |
| Code | HTTP | Message |
|---|---|---|
AGENT_RUNTIME_TIMEOUT | 504 | Agent execution timed out |
AGENT_RUNTIME_FAILED | 500 | Agent execution failed |
AGENT_EXTERNAL_PROVIDER_DOWN | 503 | AI provider unavailable |
AGENT_VALIDATION_INVALID_INPUT | 422 | Invalid agent input |
AGENT_NOTFOUND_TYPE | 404 | Unknown agent type |
| Code | HTTP | Message |
|---|---|---|
DATA_VALIDATION_MISSING_FIELD | 422 | Required field missing |
DATA_VALIDATION_INVALID_FORMAT | 422 | Invalid data format |
DATA_NOTFOUND_DOCUMENT | 404 | Document not found |
DATA_NOTFOUND_CONTRACTOR | 404 | Contractor not found |
DATA_CONFLICT_DUPLICATE | 409 | Resource already exists |
| Code | HTTP | Message |
|---|---|---|
SYS_EXTERNAL_DATABASE | 500 | Database connection error |
SYS_EXTERNAL_REDIS | 500 | Cache service error |
SYS_RATELIMIT_EXCEEDED | 429 | Rate limit exceeded |
SYS_RUNTIME_INTERNAL | 500 | Internal server error |
When adding a new error code:
ERROR_MESSAGESErrorResponse model when raising HTTPException| Pattern | Problem | Correct Approach |
|---|---|---|
Unstructured error strings (raise HTTPException(detail="bad input")) | No machine-readable code, inconsistent frontend handling | Use ErrorResponse model with error_code field |
Inconsistent error codes (AUTH_BAD_TOKEN vs AUTH_VALIDATION_INVALID_TOKEN) | Breaks the DOMAIN_CATEGORY_SPECIFIC convention | Follow the three-part code format defined in this skill |
| Missing user-facing messages | Frontend falls back to raw technical error text | Map every error code in the ERROR_MESSAGES record |
| Error codes not matching domain prefix | Agent errors using SYS_ prefix or vice versa | Choose domain from the Domains table before naming |
DOMAIN_CATEGORY_SPECIFIC formatERROR_MESSAGES mapApiClientError handling matches backend ErrorResponse contract[AGENT_ACTIVATED]: Error Taxonomy
[PHASE]: {Classification | Implementation | Review}
[STATUS]: {in_progress | complete}
{error analysis or implementation guidance}
[NEXT_ACTION]: {what to do next}