feat: add structured error response format with error codes

[dinahmaccodes]

Structured Error Response Format Implementation

This PR implements a standardized error response format across all backend API endpoints with error codes, correlation IDs, and comprehensive error handling.

Changes Made

✅ Error Response Schema

• Created StandardErrorResponseDto with all required fields (success, statusCode, errorCode, message, timestamp, path, correlationId)
• Added support for validation errors array with field-level details
• Implemented environment-aware debug context (development/test only)

✅ Error Code System

• Implemented error code registry with pattern CATEGORY_NNN (AUTH_001, VAL_002, DB_001, etc.)
• Created error-codes.json configuration with 17 predefined error codes across 7 categories (AUTH, AUTHZ, VAL, DB, RPC, RATE, SYS)
• Built ErrorCodeRegistry service for centralized error code management

✅ Global Exception Filter

• Created EnhancedExceptionFilter replacing old filters
• Preserves existing RPC timeout and database error detection logic
• Automatic HTTP exception to error code mapping
• Correlation ID integration from existing interceptor

✅ Error Documentation

• Added comprehensive ERROR_HANDLING.md documentation
• Implemented generate-error-docs script for auto-generating error code documentation in Markdown and JSON formats
• Added npm script: npm run generate:error-docs

✅ Custom Application Errors

• Created ApplicationException class with error code support
• Method chaining for adding context: .withContext(key, value)
• Context data appears in debug mode for easier troubleshooting

✅ Backward Compatibility

• All existing error response fields preserved (success, statusCode, message, timestamp, path)
• Added new fields (errorCode, correlationId, debugContext) without breaking changes
• Updated existing DTOs to extend new standard format

Error Code Categories

Category	Description	Example Codes
AUTH	Authentication	AUTH_001, AUTH_002
AUTHZ	Authorization	AUTHZ_001
VAL	Validation	VAL_001
DB	Database	DB_001, DB_002, DB_003, DB_004
RPC	Blockchain RPC	RPC_001, RPC_002, RPC_003, RPC_004
RATE	Rate Limiting	RATE_001
SYS	System/HTTP	SYS_400, SYS_404, SYS_409, SYS_500

Example Error Response

{
  "success": false,
  "statusCode": 400,
  "errorCode": "VAL_001",
  "message": "Validation failed. Please check your input.",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/v2/goals",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "goalName",
      "value": "",
      "constraints": {
        "isNotEmpty": "goalName should not be empty"
      }
    }
  ]
}

Files Changed

• ✅ backend/src/common/config/error-codes.json - Error code configuration
• ✅ backend/src/common/dto/standard-error-response.dto.ts - Standardized DTOs
• ✅ backend/src/common/services/error-code-registry.service.ts - Registry service
• ✅ backend/src/common/exceptions/application.exception.ts - Custom exception class
• ✅ backend/src/common/filters/enhanced-exception.filter.ts - Unified exception filter
• ✅ backend/src/common/dto/api-error-response.dto.ts - Updated existing DTOs
• ✅ backend/src/main.ts - Integrated new filter
• ✅ backend/src/scripts/generate-error-docs.ts - Documentation generator
• ✅ backend/docs/ERROR_HANDLING.md - Complete documentation
• ✅ backend/package.json - Added script, fixed dependencies

Testing

The error handling system has been integrated and maintains backward compatibility. All existing error flows continue to work while providing enhanced error information.

Checklist

• Design error response schema
• Create global exception filter
• Implement error code system
• Add error documentation
• Include request correlation ID
• Maintain backward compatibility
• Add documentation generation script
• Update package.json dependencies

Closes #900

---

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
nestera	Skipped		Jun 2, 2026 7:37am

[drips-wave]

@dinahmaccodes Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits