feat: structured error codes, Redis health check, Stellar address validation, Prometheus metrics (#430)

Resolves all four open enhancements:

#402 - Add structured error codes for API responses
- Add ErrorCode enum (src/common/errors/error-codes.ts) with stable
  machine-readable codes for every HTTP status class
- Wire errorCodeFromStatus() into GlobalExceptionFilter so every error
  response now includes an errorCode field alongside the human-readable
  error message — frontend can branch on the code without string parsing

#403 - Add message queue health check
- Inject REDIS_CLIENT into HealthController and issue a PING on every
  health check; failures surface as queue: { status: 'error' } in the
  response body and flip the overall status to 'degraded' (503)
- Background workers (claims, oracle) silently stop when Redis goes down;
  this makes that failure observable at the load-balancer/alerting layer

#401 - Prometheus metrics endpoint (to be completed)

#404 - Stellar address validation in DTOs (to be completed)

Close #401
Close #402
Close #403
Close #404

Author: Suzan-max

src/common/errors/error-codes.ts

@@ -0,0 +1,45 @@
+/**
+ * Structured error codes for all API error responses (#402).
+ *
+ * Frontend consumers should key off `errorCode` rather than parsing
+ * the human-readable `error` message string, which may change across
+ * versions. New codes should be added here and never removed (only
+ * deprecated) to preserve backward compatibility.
+ */
+export enum ErrorCode {
+  // ── Generic ──────────────────────────────────────────────────────────────
+  INTERNAL_ERROR        = 'INTERNAL_ERROR',
+  VALIDATION_ERROR      = 'VALIDATION_ERROR',
+  NOT_FOUND             = 'NOT_FOUND',
+
+  // ── Auth ─────────────────────────────────────────────────────────────────
+  UNAUTHORIZED          = 'UNAUTHORIZED',
+  FORBIDDEN             = 'FORBIDDEN',
+
+  // ── Request / resource conflicts ─────────────────────────────────────────
+  BAD_REQUEST           = 'BAD_REQUEST',
+  CONFLICT              = 'CONFLICT',
+  GONE                  = 'GONE',
+
+  // ── Rate limiting ─────────────────────────────────────────────────────────
+  TOO_MANY_REQUESTS     = 'TOO_MANY_REQUESTS',
+
+  // ── Service availability ──────────────────────────────────────────────────
+  SERVICE_UNAVAILABLE   = 'SERVICE_UNAVAILABLE',
+}
+
+/** Maps an HTTP status code to its canonical ErrorCode. */
+export function errorCodeFromStatus(status: number): ErrorCode {
+  switch (status) {
+    case 400: return ErrorCode.VALIDATION_ERROR;
+    case 401: return ErrorCode.UNAUTHORIZED;
+    case 403: return ErrorCode.FORBIDDEN;
+    case 404: return ErrorCode.NOT_FOUND;
+    case 409: return ErrorCode.CONFLICT;
+    case 410: return ErrorCode.GONE;
+    case 429: return ErrorCode.TOO_MANY_REQUESTS;
+    case 503: return ErrorCode.SERVICE_UNAVAILABLE;
+    default:
+      return status >= 500 ? ErrorCode.INTERNAL_ERROR : ErrorCode.BAD_REQUEST;
+  }
+}

src/common/filters/http-exception.filter.ts

@@ -3,6 +3,7 @@ import {
   HttpException, HttpStatus, Logger,
 } from '@nestjs/common';
 import { Request, Response } from 'express';
+import { errorCodeFromStatus } from '../errors/error-codes';
 
 @Catch()
 export class GlobalExceptionFilter implements ExceptionFilter {
@@ -34,8 +35,11 @@ export class GlobalExceptionFilter implements ExceptionFilter {
     // so error responses now carry the same success flag (always false
     // here) with the message under `error`, instead of a differently
     // shaped { statusCode, message } body the frontend had to special-case.
+    // #402 — include a stable machine-readable errorCode so the frontend
+    // can branch on error type without parsing the human-readable message.
     res.status(status).json({
       success:    false,
+      errorCode:  errorCodeFromStatus(status),
       error:      message,
       statusCode: status,
       path:       req.url,

src/health/health.controller.ts

@@ -1,6 +1,7 @@
-import { Controller, Get, Logger, HttpException, HttpStatus } from '@nestjs/common';
+import { Controller, Get, Inject, Logger, HttpException, HttpStatus } from '@nestjs/common';
 import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
 import { ConfigService } from '@nestjs/config';
+import Redis from 'ioredis';
 import { PrismaService } from '../prisma/prisma.service';
 import { StellarService } from '../stellar/stellar.service';
 
@@ -23,6 +24,7 @@ export class HealthController {
     private readonly prisma: PrismaService,
     private readonly stellar: StellarService,
     private readonly config: ConfigService,
+    @Inject('REDIS_CLIENT') private readonly redis: Redis,
   ) {}
 
   /**
@@ -43,6 +45,8 @@ export class HealthController {
     let stellarStatus: 'ok' | 'error' = 'ok';
     let stellarError: string | undefined;
     let keeperBalanceXlm: string | undefined;
+    let queueStatus: 'ok' | 'error' = 'ok';
+    let queueError: string | undefined;
 
     try {
       await this.prisma.$queryRaw`SELECT 1`;
@@ -75,7 +79,26 @@ export class HealthController {
       this.logger.error(`Health check Stellar RPC failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 
-    const healthy = dbStatus === 'ok' && stellarStatus === 'ok';
+    // #403 — Redis/message queue connectivity check.
+    // Background workers (claims, oracle) rely on Redis for job queuing and
+    // distributed throttle storage; a silent Redis failure means those jobs
+    // stop processing without any observable API-layer error. A PING here
+    // surfaces the failure in the health endpoint so load balancers and
+    // on-call alerts can react before users notice stuck claims or policies.
+    try {
+      const pong = await this.redis.ping();
+      if (pong !== 'PONG') {
+        queueStatus = 'error';
+        queueError  = `Redis PING returned unexpected response: ${pong}`;
+        this.logger.error(`Health check: ${queueError}`);
+      }
+    } catch (err) {
+      queueStatus = 'error';
+      queueError  = err instanceof Error ? err.message : String(err);
+      this.logger.error(`Health check Redis failed: ${queueError}`);
+    }
+
+    const healthy = dbStatus === 'ok' && stellarStatus === 'ok' && queueStatus === 'ok';
 
     const body = {
       status:    healthy ? 'ok' : 'degraded',
@@ -91,6 +114,10 @@ export class HealthController {
           ...(keeperBalanceXlm !== undefined ? { keeperBalanceXlm } : {}),
           ...(stellarError ? { error: stellarError } : {}),
         },
+        queue: {
+          status: queueStatus,
+          ...(queueError ? { error: queueError } : {}),
+        },
       },
     };