Merge pull request #252 from Sundriveauto/feat/error-handling-boundaries

feat: centralized error handling, boundaries, retry & support playbook

Author: jhayniffy

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

@@ -8,6 +8,29 @@ import {
 } from '@nestjs/common';
 import { Request, Response } from 'express';
 
+/**
+ * Maps Stellar / Soroban error strings to stable API error codes.
+ * Keeps raw blockchain internals out of client-facing responses.
+ */
+const STELLAR_ERROR_MAP: Record<string, string> = {
+  tx_failed: 'TRANSACTION_FAILED',
+  tx_bad_auth: 'SIGNATURE_INVALID',
+  tx_insufficient_fee: 'INSUFFICIENT_FEE',
+  tx_no_account: 'INVALID_WALLET_ADDRESS',
+  op_no_trust: 'TRANSACTION_FAILED',
+  op_underfunded: 'INSUFFICIENT_BALANCE',
+  ledgerClosed: 'LEDGER_CLOSED',
+  timeout: 'TIMEOUT_ERROR',
+};
+
+function normalizeStellarError(raw: string): string | undefined {
+  const lower = raw.toLowerCase();
+  for (const [key, code] of Object.entries(STELLAR_ERROR_MAP)) {
+    if (lower.includes(key.toLowerCase())) return code;
+  }
+  return undefined;
+}
+
 @Catch()
 export class HttpExceptionFilter implements ExceptionFilter {
   private readonly logger = new Logger(HttpExceptionFilter.name);
@@ -22,11 +45,17 @@ export class HttpExceptionFilter implements ExceptionFilter {
         ? exception.getStatus()
         : HttpStatus.INTERNAL_SERVER_ERROR;
 
-    const message =
+    const rawResponse =
       exception instanceof HttpException
         ? exception.getResponse()
         : 'Internal server error';
 
+    // Normalize Stellar error codes when present
+    let errorCode: string | undefined;
+    if (exception instanceof Error) {
+      errorCode = normalizeStellarError(exception.message);
+    }
+
     // Log 5xx errors with stack trace; 4xx are client errors — debug level
     if (status >= 500) {
       this.logger.error(
@@ -41,8 +70,12 @@ export class HttpExceptionFilter implements ExceptionFilter {
       statusCode: status,
       timestamp: new Date().toISOString(),
       path: request.url,
-      requestId: request.requestId, // propagate correlation ID into error body
-      message,
+      requestId: request.requestId, // correlation ID for support escalation
+      ...(errorCode ? { error: errorCode } : {}),
+      message:
+        typeof rawResponse === 'string'
+          ? rawResponse
+          : (rawResponse as Record<string, unknown>).message ?? rawResponse,
     });
   }
 }

docs/ops/error-support-playbook.md

@@ -0,0 +1,100 @@
+# Error & Support Playbook
+
+## Overview
+
+Every API error response includes a `requestId` (correlation ID) that links the
+user-facing error to a specific backend log entry. Support agents should always
+ask users for this reference before escalating.
+
+---
+
+## 1. Finding a Correlation ID
+
+### From the UI
+Users see the reference in error toasts and inline error messages:
+> "Something went wrong. (Ref: `req_abc123`)"
+
+### From the API response body
+```json
+{
+  "statusCode": 500,
+  "requestId": "req_abc123",
+  "error": "SERVER_ERROR",
+  "message": "Internal server error"
+}
+```
+
+### From response headers
+```
+x-request-id: req_abc123
+```
+
+---
+
+## 2. Log Lookup
+
+### NestJS backend (structured JSON logs)
+```bash
+# Grep by requestId in production logs
+grep '"requestId":"req_abc123"' /var/log/app/app.log
+
+# Or with jq
+cat /var/log/app/app.log | jq 'select(.requestId == "req_abc123")'
+```
+
+### Grafana / Loki
+```logql
+{app="niffyinsur-backend"} |= "req_abc123"
+```
+
+---
+
+## 3. Error Code Reference
+
+| Code | HTTP | Meaning | Action |
+|------|------|---------|--------|
+| `UNAUTHORIZED` | 401 | Session expired | Ask user to reconnect wallet |
+| `FORBIDDEN` | 403 | Insufficient role | Verify user permissions |
+| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests | Wait and retry; check for abuse |
+| `TRANSACTION_FAILED` | 400 | Stellar tx rejected | Check Stellar explorer with tx hash |
+| `SIGNATURE_INVALID` | 400 | Bad wallet signature | Ask user to retry signing |
+| `INSUFFICIENT_BALANCE` | 400 | Not enough XLM/token | User needs to fund wallet |
+| `LEDGER_CLOSED` | 400 | Tx missed ledger window | Resubmit transaction |
+| `SOROBAN_RPC_ERROR` | 502 | RPC node issue | Check RPC node health; retry |
+| `OPEN_CLAIM_EXISTS` | 409 | Duplicate claim attempt | Explain existing open claim |
+| `SERVER_ERROR` | 500 | Unhandled exception | Escalate with requestId |
+
+---
+
+## 4. Stellar Transaction Debugging
+
+1. Extract `transactionHash` from the error details or user report.
+2. Look up on Stellar Expert:
+   - Testnet: `https://stellar.expert/explorer/testnet/tx/<hash>`
+   - Mainnet: `https://stellar.expert/explorer/public/tx/<hash>`
+3. Check the result code (e.g. `tx_failed`, `op_underfunded`).
+4. Map to the error code table above.
+
+> **Security**: Never ask users to share private keys, seed phrases, or signed
+> XDR outside of a verified secure developer tool. These are never required for
+> support escalation.
+
+---
+
+## 5. Escalation Path
+
+1. **Tier 1** — User self-service: retry button in UI, reconnect wallet.
+2. **Tier 2** — Support agent: collect `requestId`, look up logs, check Stellar explorer.
+3. **Tier 3** — Engineering: provide `requestId` + full log context + Stellar tx hash.
+
+---
+
+## 6. PII Policy for Error Events
+
+Anonymized error events forwarded to observability tools **must not** include:
+- Wallet addresses (truncate to first 6 + last 4 chars if needed for grouping)
+- Email addresses
+- IP addresses (hash or omit)
+- Private keys, seeds, or signed XDR (never, under any circumstances)
+
+See `backend/src/maintenance/privacy.service.ts` for the data-scrubbing implementation.

frontend/src/app/claims/error.tsx

@@ -0,0 +1,5 @@
+'use client';
+import { RouteError } from '@/components/route-error';
+export default function ClaimsError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+  return <RouteError error={error} reset={reset} area="Claims Board" />;
+}

frontend/src/app/policy/error.tsx

@@ -0,0 +1,5 @@
+'use client';
+import { RouteError } from '@/components/route-error';
+export default function PolicyError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+  return <RouteError error={error} reset={reset} area="Policy" />;
+}

frontend/src/app/quote/error.tsx

@@ -0,0 +1,5 @@
+'use client';
+import { RouteError } from '@/components/route-error';
+export default function QuoteError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+  return <RouteError error={error} reset={reset} area="Quote" />;
+}

frontend/src/app/support/error.tsx

@@ -0,0 +1,5 @@
+'use client';
+import { RouteError } from '@/components/route-error';
+export default function SupportError({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+  return <RouteError error={error} reset={reset} area="Support" />;
+}

frontend/src/components/error-boundary.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import React from 'react';
+import { AlertTriangle, RefreshCw } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { resolveErrorMessage, getCorrelationId } from '@/lib/errors';
+
+interface Props {
+  children: React.ReactNode;
+  /** Shown in the fallback heading, e.g. "Claims Board" */
+  area?: string;
+}
+
+interface State {
+  error: unknown;
+  hasError: boolean;
+}
+
+/**
+ * Error boundary for a major feature area.
+ *
+ * - In development: shows a collapsible technical details panel.
+ * - In production: shows only a user-safe message + correlation ID.
+ * - Never renders private keys, seeds, or raw XDR.
+ */
+export class ErrorBoundary extends React.Component<Props, State> {
+  state: State = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: unknown): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: unknown, info: React.ErrorInfo) {
+    // Forward anonymized event to observability (no PII, no stack in prod)
+    if (typeof window !== 'undefined' && process.env.NODE_ENV === 'production') {
+      const correlationId = getCorrelationId(error);
+      // Replace with your observability SDK call, e.g. Sentry.captureException
+      console.error('[ErrorBoundary]', {
+        area: this.props.area,
+        correlationId,
+        componentStack: info.componentStack?.slice(0, 200), // truncate
+      });
+    } else {
+      console.error('[ErrorBoundary dev]', error, info);
+    }
+  }
+
+  reset = () => this.setState({ hasError: false, error: null });
+
+  render() {
+    if (!this.state.hasError) return this.props.children;
+
+    const { error } = this.state;
+    const userMessage = resolveErrorMessage(error);
+    const correlationId = getCorrelationId(error);
+    const isDev = process.env.NODE_ENV !== 'production';
+
+    return (
+      <div
+        role="alert"
+        className="flex flex-col items-center justify-center min-h-[200px] p-8 text-center gap-4"
+      >
+        <AlertTriangle className="h-10 w-10 text-destructive" aria-hidden />
+        <div>
+          <p className="font-semibold text-lg">
+            {this.props.area ? `${this.props.area} unavailable` : 'Something went wrong'}
+          </p>
+          <p className="text-muted-foreground text-sm mt-1">{userMessage}</p>
+          {correlationId && (
+            <p className="text-xs text-muted-foreground mt-2">
+              Support reference:{' '}
+              <code className="font-mono">{correlationId}</code>
+            </p>
+          )}
+        </div>
+
+        {isDev && error instanceof Error && (
+          <details className="w-full max-w-xl text-left text-xs border rounded p-3 bg-muted">
+            <summary className="cursor-pointer font-medium">Technical details (dev only)</summary>
+            <pre className="mt-2 whitespace-pre-wrap break-all opacity-80">
+              {error.stack ?? error.message}
+            </pre>
+          </details>
+        )}
+
+        <Button variant="outline" size="sm" onClick={this.reset}>
+          <RefreshCw className="h-4 w-4 mr-2" aria-hidden />
+          Try again
+        </Button>
+      </div>
+    );
+  }
+}

frontend/src/components/route-error.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+import { useEffect } from 'react';
+import { AlertTriangle, RefreshCw } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { resolveErrorMessage, getCorrelationId } from '@/lib/errors';
+
+interface Props {
+  error: Error & { digest?: string };
+  reset: () => void;
+  area: string;
+}
+
+/**
+ * Shared render for Next.js route-level error.tsx files.
+ * Keeps all feature-area error UIs consistent.
+ */
+export function RouteError({ error, reset, area }: Props) {
+  const isDev = process.env.NODE_ENV !== 'production';
+  const correlationId = getCorrelationId(error) ?? error.digest;
+
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'production') {
+      // Forward anonymized event — replace with your observability SDK
+      console.error('[RouteError]', { area, correlationId });
+    } else {
+      console.error('[RouteError dev]', error);
+    }
+  }, [error, area, correlationId]);
+
+  return (
+    <div
+      role="alert"
+      className="flex flex-col items-center justify-center min-h-[300px] p-8 text-center gap-4"
+    >
+      <AlertTriangle className="h-10 w-10 text-destructive" aria-hidden />
+      <div>
+        <p className="font-semibold text-lg">{area} unavailable</p>
+        <p className="text-muted-foreground text-sm mt-1">{resolveErrorMessage(error)}</p>
+        {correlationId && (
+          <p className="text-xs text-muted-foreground mt-2">
+            Support reference: <code className="font-mono">{correlationId}</code>
+          </p>
+        )}
+      </div>
+
+      {isDev && (
+        <details className="w-full max-w-xl text-left text-xs border rounded p-3 bg-muted">
+          <summary className="cursor-pointer font-medium">Technical details (dev only)</summary>
+          <pre className="mt-2 whitespace-pre-wrap break-all opacity-80">
+            {error.stack ?? error.message}
+          </pre>
+        </details>
+      )}
+
+      <Button variant="outline" size="sm" onClick={reset}>
+        <RefreshCw className="h-4 w-4 mr-2" aria-hidden />
+        Try again
+      </Button>
+    </div>
+  );
+}

frontend/src/components/ui/index.ts

@@ -48,6 +48,7 @@ export {
 } from './card'
 export { Badge, badgeVariants } from './badge'
 export { Stepper, StepContent, type Step } from './stepper'
+export { InlineError } from './inline-error'
 export { VoteEducationPanel } from '../claims/vote-education-panel'
 export { VoteTally } from '../claims/vote-tally'
 export { VoteConfirmModal } from '../claims/vote-confirm-modal'

frontend/src/components/ui/inline-error.tsx

@@ -0,0 +1,44 @@
+'use client';
+
+import { AlertCircle, RefreshCw } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { resolveErrorMessage, getCorrelationId } from '@/lib/errors';
+
+interface InlineErrorProps {
+  error: unknown;
+  /** If provided, renders a retry button */
+  onRetry?: () => void;
+  className?: string;
+}
+
+/**
+ * Standardized inline error for forms and data-fetch sections.
+ * Shows user-safe message + optional correlation ID + optional retry button.
+ */
+export function InlineError({ error, onRetry, className }: InlineErrorProps) {
+  const message = resolveErrorMessage(error);
+  const correlationId = getCorrelationId(error);
+
+  return (
+    <div
+      role="alert"
+      className={`flex items-start gap-3 rounded-md border border-destructive/40 bg-destructive/5 p-3 text-sm ${className ?? ''}`}
+    >
+      <AlertCircle className="h-4 w-4 mt-0.5 shrink-0 text-destructive" aria-hidden />
+      <div className="flex-1 min-w-0">
+        <p className="text-destructive font-medium">{message}</p>
+        {correlationId && (
+          <p className="text-xs text-muted-foreground mt-0.5">
+            Ref: <code className="font-mono">{correlationId}</code>
+          </p>
+        )}
+      </div>
+      {onRetry && (
+        <Button variant="ghost" size="sm" onClick={onRetry} className="shrink-0 h-7 px-2">
+          <RefreshCw className="h-3 w-3 mr-1" aria-hidden />
+          Retry
+        </Button>
+      )}
+    </div>
+  );
+}