common-error-handling

Common Error Handling Standards

Priority: P1 (OPERATIONAL)

Consistent, predictable error handling is the backbone of maintainable systems. Errors are first-class citizens — design them explicitly.

🏗 Error Response Shape (HTTP APIs)

All API errors MUST use a consistent envelope:

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "The requested user does not exist.",
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "details": []
  }
}

🗂 Error Classification

📦 Error Wrapping vs Replacement

• Wrap when adding context: fmt.Errorf("processOrder: %w", err) (Go) / new ServiceError('msg', { cause: err }) (JS).
• Replace only when the original error leaks sensitive internal details.
• Never swallow: Catch without logging or re-throwing hides bugs — forbidden.

🛡 Boundary Placement

• API Layer: Translate domain/infrastructure errors into HTTP responses. Use a global exception filter/middleware.
• Domain Layer: Throw domain-specific errors (e.g., InsufficientStockError). Never reference HTTP status codes.
• Infrastructure Layer: Throw infrastructure errors (e.g., DatabaseConnectionError). Wrap 3rd party exceptions.
• Never: Let infrastructure errors (raw DB/network exceptions) bubble up to the API response.

Request → [API Layer: maps to HTTP] → [Domain: business errors] → [Infra: DB/network errors]

🔢 Error Code Design

• Codes are permanent IDs — treat them like API contracts. Once published, never rename.
• Format: <DOMAIN>_<NOUN>_<VERB> → ORDER_PAYMENT_FAILED, USER_EMAIL_DUPLICATE.
• Define in a centralized constants file; never inline magic strings.

Anti-Patterns

• No catch(e) {}: Always log or re-throw.
• No stack traces in responses: Leak internal structure to attackers.
• No generic 500 for validation: Use 400 with details.
• No HTTP status codes in domain layer: Domain errors are business concepts, not transport decisions.
• No error-code proliferation: Prefer a small, well-documented set over one code per exception class.