Implement Centralized API Error Handling

[A6dulmalik]

Implement Centralized API Error Handling

Priority

P0 — Critical

Labels

backend architecture security priority: p0

Description

Mind Block requires a consistent error-handling strategy across all backend modules. Currently, different services may return errors in different formats, making it difficult for the frontend to reliably display meaningful feedback.

A centralized exception-handling system should provide predictable API error responses while preventing sensitive internal information from being exposed to users.

Objective

Implement a global NestJS exception filter and standardized API error response format.

Standard Error Response

All API errors should follow a consistent structure:

{
  "success": false,
  "statusCode": 400,
  "error": "Bad Request",
  "message": "A human-readable error message",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-08-20T12:00:00.000Z",
  "path": "/api/game-sessions"
}

Error Categories

Support standardized error codes for:

VALIDATION_ERROR
UNAUTHORIZED
FORBIDDEN
NOT_FOUND
CONFLICT
RATE_LIMITED
SESSION_EXPIRED
SESSION_INVALID
CHALLENGE_UNAVAILABLE
INVALID_ANSWER
DUPLICATE_SUBMISSION
REWARD_NOT_ELIGIBLE
BLOCKCHAIN_ERROR
INTERNAL_SERVER_ERROR

Requirements

• Create a global exception filter.
• Standardize error response structures.
• Map NestJS exceptions to application error codes.
• Handle validation errors.
• Handle database errors safely.
• Handle authentication errors.
• Handle authorization errors.
• Handle unexpected server errors.
• Prevent stack traces from being exposed in production.
• Log unexpected server errors.
• Include a unique request ID where applicable.

Acceptance Criteria

• All API errors follow a consistent response structure.
• Validation errors return meaningful field-level information.
• Authentication errors return standardized responses.
• Authorization errors return standardized responses.
• Database errors do not expose sensitive information.
• Stack traces are hidden in production.
• Unexpected errors are logged.
• Error codes are documented.
• Unit tests cover common error scenarios.

Dependencies

None.

[samkay-ops]

Hi team,
I'm applying to work on this issue.
I have strong experience with TypeScript, NestJS, and Soroban smart contracts. I will deliver clean, tested code following the acceptance criteria.
Ready to start immediately.
Best regards,
samkay-ops

[nafiuishaaq]

Hello Maintainer, i will like to work on this issue

[grantfox-oss]

🦊 GrantFox — @nafiuishaaq has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #638)
2. Your PR will be reviewed by the MindBlockLabs maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@nafiuishaaq's PR #647 was approved and merged by @A6dulmalik.

🏆 @nafiuishaaq: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,102 total points). Track your full progress on GrantFox.

👏 Great work, @nafiuishaaq! Keep contributing to MindBlockLabs.