Gap: Error Handling Standards

Status: 🔴 Not Started Priority: Important (Pre-Scale) Estimated Effort: 1-2 days

What's Missing

Comprehensive error handling documentation including:

• Error Code Catalog

  • Complete list of all error codes
  • When to use each code
  • User-facing error messages
  • Internal error messages

• Error Response Format

  • Standardized JSON structure (exists but needs expansion)
  • Field-level validation errors
  • Multiple error aggregation
  • Error metadata (correlation IDs, timestamps)

• Logging Standards

  • What to log at ERROR vs WARN vs INFO
  • Structured logging format
  • PII exclusion from logs
  • Error context capture (user_id, org_id, request_id)

• Error Propagation

  • Repository → Service → Handler error flow
  • When to wrap errors vs. return as-is
  • Error transformation at boundaries
  • Preserving error context

• Client Error Handling

  • Retry-able vs. non-retry-able errors
  • Client-side error display recommendations
  • Error recovery strategies
  • User-friendly error messages

Why Important

1. User Experience - Clear error messages improve UX
2. Debugging - Consistent errors easier to debug
3. Monitoring - Standardized errors easier to monitor
4. Compliance - HIPAA requires audit trail of errors

Current State

• Error types defined in architecture (AppError, typed errors)
• Basic error handling in place
• No comprehensive catalog
• No PII-in-logs guidelines

Recommended Location

docs/standards/error-handling.md

Success Criteria

• [ ] Complete error code catalog
• [ ] Logging standards documented
• [ ] PII exclusion guidelines
• [ ] Error propagation patterns documented