[Feature] Standardize API response format and error codes

[Josue19-08]

➡️ Title

Standardize API response format and error codes

📘 Description

Create a consistent response format across all API endpoints and standardize error codes. Currently, different controllers return different response structures making frontend integration inconsistent and error handling unpredictable.

Context: Controllers like auth.controller.ts, project.controller.ts, and wallet.controller.ts use different response formats and inconsistent error handling, making the API difficult to consume reliably.

✅ Acceptance Criteria

Create response wrapper utilities

• Create src/utils/api-response.ts:

  • successResponse(data, message, meta?) function
  • errorResponse(error, code, details?) function
  • paginatedResponse(data, pagination) function
  • Consistent structure for all API responses

• Create src/types/api-response.ts:

  • ApiResponse<T> interface for all responses
  • ApiError interface for error responses
  • PaginationMeta interface for paginated responses
  • ErrorCode enum with all possible error codes

Define error code standards

• Create src/constants/error-codes.ts:
  • Authentication errors (AUTH_001, AUTH_002, etc.)
  • Validation errors (VAL_001, VAL_002, etc.)
  • Database errors (DB_001, DB_002, etc.)
  • Stellar/Blockchain errors (STL_001, STL_002, etc.)
  • External service errors (EXT_001, EXT_002, etc.)

Update authentication controller

• Refactor src/controllers/auth.controller.ts:
  • Replace inconsistent response format with standardized wrapper
  • Use proper error codes for different failure scenarios
  • Add request validation with structured error responses
  • Implement consistent success response format

Update wallet controller

• Refactor src/controllers/wallet.controller.ts:
  • Standardize all endpoint responses (createWallet, exportEncryptedKeyHandler, etc.)
  • Use consistent error codes for wallet-related errors
  • Add proper validation error responses
  • Implement structured success responses with metadata

Update project controller

• Refactor src/controllers/project.controller.ts:
  • Standardize project CRUD responses
  • Use consistent pagination format for getPaginatedProjectsController
  • Implement proper error handling for project operations
  • Add metadata for project-related operations

Create middleware for response formatting

• Create src/middleware/response-formatter.ts:
  • Middleware to automatically format responses
  • Error handling middleware for unhandled exceptions
  • Request validation error formatting
  • Add response timing and request ID

Update existing endpoints

• Update all routes to use standardized responses:
  • src/routes/auth.routes.ts
  • src/routes/wallets.routes.ts
  • src/routes/project.routes.ts
  • src/routes/health.routes.ts

Example response structures

// utils/api-response.ts
export const successResponse = <T>(data: T, message?: string, meta?: any) => ({
  success: true,
  data,
  message: message || 'Operation successful',
  meta,
  timestamp: new Date().toISOString()
});

export const errorResponse = (error: string, code: ErrorCode, details?: any) => ({
  success: false,
  error: {
    code,
    message: error,
    details
  },
  timestamp: new Date().toISOString()
});

// Example usage in controller
res.status(200).json(successResponse(project, 'Project created successfully', {
  id: project.id,
  contractAddress: project.contract_address
}));

Status code standardization

• Define HTTP status code usage standards:
  • 200: Successful GET operations
  • 201: Successful POST operations (creation)
  • 400: Client errors (validation, bad request)
  • 401: Authentication errors
  • 403: Authorization errors
  • 404: Resource not found
  • 409: Conflict errors (duplicate resources)
  • 500: Server errors

Error logging integration

• Integrate with existing logging:
  • Log all errors with consistent format
  • Add error correlation IDs
  • Include request context in error logs
  • Separate user-facing and internal error messages

Documentation updates

• Update API documentation:
  • Document standard response format
  • List all error codes with descriptions
  • Provide examples for each endpoint
  • Add troubleshooting guide for common errors

⚠ Use kebab-case for all file and folder names.
⚠ Do not use default alias imports or relative paths like ../../components/foo.
⚠ Use alias paths with @, e.g. @/components/foo.
⚠ Structure the code with reusable components and reuse existing ones.

[JosueBrenes]

Hi, can i work in this issue? please

[yhoungdev]

Hey @Josue19-08 i would love to take on this if it is still open, i am a recurring contributor on this repository, i would appreciate if this is assigned to me, thank you.