diff --git a/.env.local.example b/.env.local.example
index 5694add..431fc8f 100644
--- a/.env.local.example
+++ b/.env.local.example
@@ -33,3 +33,8 @@ INVOICE_CONTRACT_ID=C...
 SIGNER_SECRET_KEY=S...
 NETWORK_PASSPHRASE=Standalone Network ; February 2025
 SOROBAN_RPC_URL=http://localhost:8000/soroban/rpc
+
+# CORS — comma-separated allowlist of browser origins allowed to call the API.
+# Each entry is a bare origin (scheme://host[:port]); no paths, trailing slash or "*".
+# Requests from any other origin are rejected with 403.
+CORS_ORIGINS=http://localhost:5173
diff --git a/.env.mainnet.example b/.env.mainnet.example
index 4b0297f..bb55ddd 100644
--- a/.env.mainnet.example
+++ b/.env.mainnet.example
@@ -12,3 +12,8 @@ USDC_CONTRACT_ID=C...
 REDIS_URL=redis://localhost:6379
 RATE_LIMIT_POINTS=60
 RATE_LIMIT_DURATION=60
+
+# CORS — comma-separated allowlist of browser origins allowed to call the API.
+# Each entry is a bare origin (scheme://host[:port]); no paths, trailing slash or "*".
+# List only production frontends here; never use a wildcard on mainnet.
+CORS_ORIGINS=https://app.your-frontend.example
diff --git a/.env.testnet.example b/.env.testnet.example
index 567d715..92e10d5 100644
--- a/.env.testnet.example
+++ b/.env.testnet.example
@@ -12,3 +12,7 @@ USDC_CONTRACT_ID=C...
 REDIS_URL=redis://localhost:6379
 RATE_LIMIT_POINTS=60
 RATE_LIMIT_DURATION=60
+
+# CORS — comma-separated allowlist of browser origins allowed to call the API.
+# Each entry is a bare origin (scheme://host[:port]); no paths, trailing slash or "*".
+CORS_ORIGINS=https://testnet.your-frontend.example
diff --git a/comebackhere-backend/package.json b/comebackhere-backend/package.json
index c4564cf..1e952e2 100644
--- a/comebackhere-backend/package.json
+++ b/comebackhere-backend/package.json
@@ -21,6 +21,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@types/cors": "^2.8.19",
     "@types/express": "^4.17.21",
     "@types/ioredis": "^5.0.0",
     "@types/node": "^20.11.0",
diff --git a/comebackhere-backend/src/app.ts b/comebackhere-backend/src/app.ts
index 08e9df3..71fb22a 100644
--- a/comebackhere-backend/src/app.ts
+++ b/comebackhere-backend/src/app.ts
@@ -1,4 +1,5 @@
 import express from "express"
+import helmet from "helmet"
 import swaggerUi from "swagger-ui-express"
 import invoicesRouter from "./routes/invoices.js"
 import complianceRouter from "./routes/compliance.js"
@@ -11,15 +12,69 @@ import analyticsRouter from "./routes/analytics.js"
 import { startComplianceIndexer } from "./services/compliance-indexer.js"
 import { rateLimitMiddleware } from "./middleware/rateLimiter.js"
 import { correlationIdMiddleware } from "./middleware/correlationId.js"
+import { errorHandler, notFoundHandler } from "./middleware/errorHandler.js"
+import { createCorsMiddleware } from "./middleware/cors.js"
+import { parseCorsOrigins } from "./lib/env.js"
 import { openapiSpec } from "./openapi.js"
 import { renderMetrics } from "./lib/metrics.js"
 
-export function createApp() {
+/** Maximum accepted JSON body size; larger requests get a 413 envelope. */
+export const JSON_BODY_LIMIT = "100kb"
+
+// This is a JSON API, so by default nothing may be loaded, framed or executed.
+const apiHelmet = helmet({
+  contentSecurityPolicy: {
+    useDefaults: false,
+    directives: {
+      defaultSrc: ["'none'"],
+      frameAncestors: ["'none'"],
+      baseUri: ["'none'"],
+      formAction: ["'none'"],
+    },
+  },
+})
+
+// Swagger UI serves its JS/CSS from same-origin files but also uses inline
+// <style> blocks and data: images, and "Try it out" calls back into the API.
+const swaggerHelmet = helmet({
+  contentSecurityPolicy: {
+    useDefaults: false,
+    directives: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      imgSrc: ["'self'", "data:"],
+      connectSrc: ["'self'"],
+      objectSrc: ["'none'"],
+      frameAncestors: ["'none'"],
+      baseUri: ["'self'"],
+      formAction: ["'self'"],
+    },
+  },
+})
+
+export interface CreateAppOptions {
+  /** Origins allowed to call the API cross-origin. Defaults to CORS_ORIGINS. */
+  corsOrigins?: readonly string[]
+}
+
+export function createApp(options: CreateAppOptions = {}) {
+  const corsOrigins = options.corsOrigins ?? parseCorsOrigins()
   const app = express()
-  app.use(express.json())
+  app.disable("x-powered-by")
   // Attach / propagate X-Request-Id before any other middleware so every log
-  // line and downstream call can reference the same correlation ID.
+  // line, downstream call and error envelope can reference the same
+  // correlation ID — including body-parsing errors.
   app.use(correlationIdMiddleware)
+  app.use((req, res, next) =>
+    req.path === "/api-docs" || req.path.startsWith("/api-docs/")
+      ? swaggerHelmet(req, res, next)
+      : apiHelmet(req, res, next),
+  )
+  // CORS runs before body parsing and rate limiting so preflights are cheap
+  // and disallowed origins are rejected before any work is done.
+  app.use(createCorsMiddleware(corsOrigins))
+  app.use(express.json({ limit: JSON_BODY_LIMIT }))
   app.use(rateLimitMiddleware)
 
   // ── Health ──────────────────────────────────────────────────────────────────
@@ -48,6 +103,11 @@ export function createApp() {
   app.use("/api/treasury", thresholdRouter)
   app.use("/disputes", disputesRouter)
   app.use("/api/analytics", analyticsRouter)
+
+  // ── Errors ──────────────────────────────────────────────────────────────────
+  // Everything below produces { error: { code, message, details, correlationId } }
+  app.use(notFoundHandler)
+  app.use(errorHandler)
   // Start indexing only when the application is actually created; tests omit
   // the required contract/RPC configuration and therefore remain side-effect free.
   startComplianceIndexer()
diff --git a/comebackhere-backend/src/lib/env.ts b/comebackhere-backend/src/lib/env.ts
index 3d4ca17..6af18c4 100644
--- a/comebackhere-backend/src/lib/env.ts
+++ b/comebackhere-backend/src/lib/env.ts
@@ -1,4 +1,4 @@
-import type { Response } from "express"
+import { ServiceMisconfiguredError } from "./errors.js"
 import { getNetworkPassphrase } from "./soroban.js"
 
 /**
@@ -12,8 +12,6 @@ export type ContractEnv<P extends Record<string, string>> = {
   networkPassphrase: string
 } & { [Prop in keyof P]: string }
 
-const MISSING_ENV_ERROR = "Service misconfiguration: missing required environment variables"
-
 /**
  * Reads and validates the env vars a route needs from `process.env`.
  *
@@ -22,20 +20,16 @@ const MISSING_ENV_ERROR = "Service misconfiguration: missing required environmen
  * additional property name to the env var it should be read from, e.g.
  * `{ treasuryContractId: "TREASURY_CONTRACT_ID" }`.
  *
- * If any referenced var is unset, writes a 503 with the standard
- * misconfiguration error to `res` and returns null.
+ * If any referenced var is unset, throws a {@link ServiceMisconfiguredError}
+ * (503 in the standard error envelope).
  */
-export function requireEnv<P extends Record<string, string>>(
-  res: Response,
-  vars: P,
-): ContractEnv<P> | null {
+export function requireEnv<P extends Record<string, string>>(vars: P): ContractEnv<P> {
   const missing = [
     !process.env.SOROBAN_RPC_URL ? "SOROBAN_RPC_URL" : null,
     ...Object.values(vars).filter((envName) => !process.env[envName]),
   ].filter(Boolean)
   if (missing.length > 0) {
-    res.status(503).json({ error: MISSING_ENV_ERROR })
-    return null
+    throw new ServiceMisconfiguredError()
   }
 
   const values = Object.fromEntries(
@@ -48,3 +42,57 @@ export function requireEnv<P extends Record<string, string>>(
     ...values,
   }
 }
+
+/**
+ * Parses and validates `CORS_ORIGINS`, a comma-separated allowlist of origins
+ * permitted to call the API from a browser, e.g.
+ * `http://localhost:5173,https://app.example.com`.
+ *
+ * Each entry must be a bare http(s) origin — scheme, host and optional port,
+ * with no path, query or trailing slash. Wildcards are rejected because the
+ * API has authenticated routes. Unset or empty means no cross-origin browser
+ * access is allowed (same-origin and non-browser clients are unaffected).
+ *
+ * Throws with every invalid entry listed so misconfiguration fails at startup.
+ */
+export function parseCorsOrigins(raw: string | undefined = process.env.CORS_ORIGINS): string[] {
+  const entries = (raw ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== "")
+
+  const invalid: string[] = []
+  const origins = new Set<string>()
+  for (const entry of entries) {
+    let url: URL | null = null
+    try {
+      url = new URL(entry)
+    } catch {
+      url = null
+    }
+    const isBareOrigin =
+      url !== null &&
+      !entry.includes("*") &&
+      (url.protocol === "http:" || url.protocol === "https:") &&
+      url.pathname === "/" &&
+      !entry.endsWith("/") &&
+      url.search === "" &&
+      url.hash === "" &&
+      url.username === "" &&
+      url.password === ""
+    if (!isBareOrigin) {
+      invalid.push(entry)
+      continue
+    }
+    origins.add(url!.origin)
+  }
+
+  if (invalid.length > 0) {
+    throw new Error(
+      `Invalid CORS_ORIGINS entries: ${invalid.map((e) => JSON.stringify(e)).join(", ")}. ` +
+        "Each entry must be an http(s) origin such as https://app.example.com (no path, trailing slash or wildcard).",
+    )
+  }
+
+  return [...origins]
+}
diff --git a/comebackhere-backend/src/lib/errors.ts b/comebackhere-backend/src/lib/errors.ts
new file mode 100644
index 0000000..041846b
--- /dev/null
+++ b/comebackhere-backend/src/lib/errors.ts
@@ -0,0 +1,115 @@
+import type { NextFunction, Request, RequestHandler, Response } from "express"
+
+/**
+ * Typed application errors.
+ *
+ * Routes throw one of these instead of building error responses by hand; the
+ * central handler in `middleware/errorHandler.ts` turns them into the standard
+ * envelope:
+ *
+ *   { error: { code, message, details, correlationId } }
+ */
+export class AppError extends Error {
+  readonly status: number
+  readonly code: string
+  readonly details: unknown
+
+  constructor(status: number, code: string, message: string, details: unknown = null) {
+    super(message)
+    this.name = new.target.name
+    this.status = status
+    this.code = code
+    this.details = details
+  }
+}
+
+export interface FieldIssue {
+  field: string
+  message: string
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, details: FieldIssue[] | null = null) {
+    super(400, "VALIDATION_ERROR", message, details)
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = "Unauthorized") {
+    super(401, "UNAUTHORIZED", message)
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = "Forbidden") {
+    super(403, "FORBIDDEN", message)
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message = "Resource not found") {
+    super(404, "NOT_FOUND", message)
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message: string, details: unknown = null) {
+    super(409, "CONFLICT", message, details)
+  }
+}
+
+export class PayloadTooLargeError extends AppError {
+  constructor(message = "Request body exceeds the maximum allowed size", details: unknown = null) {
+    super(413, "PAYLOAD_TOO_LARGE", message, details)
+  }
+}
+
+export class RateLimitError extends AppError {
+  constructor(retryAfter: number) {
+    super(
+      429,
+      "RATE_LIMITED",
+      "Too many requests. Please retry after the indicated number of seconds.",
+      { retryAfter },
+    )
+  }
+}
+
+export class ServiceMisconfiguredError extends AppError {
+  constructor(message = "Service misconfiguration: missing required environment variables") {
+    super(503, "SERVICE_MISCONFIGURED", message)
+  }
+}
+
+/**
+ * A Soroban contract returned a numbered error (`Error(Contract, #N)`).
+ * `contractCode` is the numeric variant documented in docs/error-codes.md.
+ */
+export class ContractError extends AppError {
+  readonly contractCode: number
+
+  constructor(contractCode: number, message: string, status = 422) {
+    super(status, "CONTRACT_ERROR", message, { contractCode })
+    this.contractCode = contractCode
+  }
+}
+
+const CONTRACT_ERROR_PATTERN = /Error\(Contract, #(\d+)\)/
+
+/** Extracts the contract error code from a Soroban host error message, if any. */
+export function parseContractErrorCode(message: string): number | null {
+  const match = CONTRACT_ERROR_PATTERN.exec(message)
+  return match ? Number(match[1]) : null
+}
+
+/**
+ * Wraps an async route handler so rejected promises reach the central error
+ * handler (Express 4 does not forward them on its own).
+ */
+export function asyncHandler<Req extends Request = Request>(
+  fn: (req: Req, res: Response, next: NextFunction) => Promise<unknown>,
+): RequestHandler {
+  return (req, res, next) => {
+    fn(req as Req, res, next).catch(next)
+  }
+}
diff --git a/comebackhere-backend/src/middleware/cors.ts b/comebackhere-backend/src/middleware/cors.ts
new file mode 100644
index 0000000..f5e3525
--- /dev/null
+++ b/comebackhere-backend/src/middleware/cors.ts
@@ -0,0 +1,57 @@
+import cors from "cors"
+import type { RequestHandler } from "express"
+import { AppError } from "../lib/errors.js"
+
+/** Request headers the frontend sends and preflight must allow. */
+export const CORS_ALLOWED_HEADERS = [
+  "Content-Type",
+  "Authorization",
+  "Idempotency-Key",
+  "X-Request-Id",
+  "X-Admin-Key",
+]
+
+/** Response headers browsers may read from cross-origin responses. */
+export const CORS_EXPOSED_HEADERS = [
+  "X-Request-Id",
+  "X-RateLimit-Limit",
+  "X-RateLimit-Remaining",
+  "X-RateLimit-Reset",
+  "Retry-After",
+]
+
+export class CorsOriginError extends AppError {
+  constructor(origin: string) {
+    super(403, "CORS_ORIGIN_NOT_ALLOWED", `Origin ${origin} is not allowed to access this API`, { origin })
+  }
+}
+
+/**
+ * CORS middleware backed by an explicit origin allowlist (see
+ * `parseCorsOrigins` in lib/env.ts).
+ *
+ * - Requests without an `Origin` header (same-origin, curl, server-to-server)
+ *   pass through untouched.
+ * - Allowlisted origins get the usual `Access-Control-*` headers, and
+ *   preflight requests are answered with 204.
+ * - Any other origin — including preflight — is rejected with 403 in the
+ *   standard error envelope.
+ */
+export function createCorsMiddleware(allowedOrigins: readonly string[]): RequestHandler {
+  const allowed = new Set(allowedOrigins)
+
+  return cors({
+    origin(origin, callback) {
+      if (!origin || allowed.has(origin)) {
+        callback(null, true)
+        return
+      }
+      callback(new CorsOriginError(origin))
+    },
+    methods: ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+    allowedHeaders: CORS_ALLOWED_HEADERS,
+    exposedHeaders: CORS_EXPOSED_HEADERS,
+    maxAge: 600,
+    optionsSuccessStatus: 204,
+  })
+}
diff --git a/comebackhere-backend/src/middleware/errorHandler.ts b/comebackhere-backend/src/middleware/errorHandler.ts
new file mode 100644
index 0000000..5136cf3
--- /dev/null
+++ b/comebackhere-backend/src/middleware/errorHandler.ts
@@ -0,0 +1,100 @@
+import type { NextFunction, Request, Response } from "express"
+import {
+  AppError,
+  ContractError,
+  NotFoundError,
+  PayloadTooLargeError,
+  parseContractErrorCode,
+} from "../lib/errors.js"
+
+/**
+ * Standard error envelope returned by every route:
+ *
+ *   { error: { code, message, details, correlationId } }
+ */
+export interface ErrorEnvelope {
+  error: {
+    code: string
+    message: string
+    details: unknown
+    correlationId: string | null
+  }
+}
+
+const CODE_BY_STATUS: Record<number, string> = {
+  400: "BAD_REQUEST",
+  401: "UNAUTHORIZED",
+  403: "FORBIDDEN",
+  404: "NOT_FOUND",
+  409: "CONFLICT",
+  413: "PAYLOAD_TOO_LARGE",
+  422: "UNPROCESSABLE_ENTITY",
+  429: "RATE_LIMITED",
+  500: "INTERNAL_ERROR",
+  502: "BAD_GATEWAY",
+  503: "SERVICE_UNAVAILABLE",
+  504: "GATEWAY_TIMEOUT",
+}
+
+/**
+ * Normalises anything thrown by a route into an {@link AppError}.
+ *
+ * Legacy helpers still throw plain `Error`s tagged with `status`; body-parser
+ * errors carry `status` and `type`. Soroban host errors that embed
+ * `Error(Contract, #N)` become a {@link ContractError} with that code.
+ */
+export function toAppError(err: unknown): AppError {
+  if (err instanceof AppError) return err
+
+  const e = (err ?? {}) as { status?: unknown; statusCode?: unknown; type?: unknown; message?: unknown; limit?: unknown }
+  const rawStatus = typeof e.status === "number" ? e.status : typeof e.statusCode === "number" ? e.statusCode : 500
+  const status = rawStatus >= 400 && rawStatus <= 599 ? rawStatus : 500
+  const message = err instanceof Error ? err.message : typeof e.message === "string" ? e.message : String(err)
+
+  if (e.type === "entity.too.large") {
+    return new PayloadTooLargeError(undefined, typeof e.limit === "number" ? { limitBytes: e.limit } : null)
+  }
+  if (e.type === "entity.parse.failed") {
+    return new AppError(400, "INVALID_JSON", "Request body is not valid JSON")
+  }
+
+  const contractCode = parseContractErrorCode(message)
+  if (contractCode !== null) {
+    return new ContractError(contractCode, message, status === 500 ? 422 : status)
+  }
+
+  return new AppError(status, CODE_BY_STATUS[status] ?? (status < 500 ? "BAD_REQUEST" : "INTERNAL_ERROR"), message)
+}
+
+export function buildErrorEnvelope(err: AppError, correlationId: string | null): ErrorEnvelope {
+  return {
+    error: {
+      code: err.code,
+      message: err.message,
+      details: err.details ?? null,
+      correlationId,
+    },
+  }
+}
+
+/** Catch-all for unmatched routes — mounted after every router. */
+export function notFoundHandler(req: Request, _res: Response, next: NextFunction): void {
+  next(new NotFoundError(`Route ${req.method} ${req.path} not found`))
+}
+
+/** Central Express error handler — must be registered last. */
+export function errorHandler(err: unknown, _req: Request, res: Response, next: NextFunction): void {
+  if (res.headersSent) {
+    next(err)
+    return
+  }
+
+  const appError = toAppError(err)
+  const correlationId = typeof res.locals.requestId === "string" ? res.locals.requestId : null
+
+  if (appError.status >= 500) {
+    console.error(`[requestId=${correlationId}] ${appError.code}: ${appError.message}`)
+  }
+
+  res.status(appError.status).json(buildErrorEnvelope(appError, correlationId))
+}
diff --git a/comebackhere-backend/src/middleware/rateLimiter.ts b/comebackhere-backend/src/middleware/rateLimiter.ts
index d51a2af..9fd3bc4 100644
--- a/comebackhere-backend/src/middleware/rateLimiter.ts
+++ b/comebackhere-backend/src/middleware/rateLimiter.ts
@@ -1,6 +1,7 @@
 import { type Request, type Response, type NextFunction } from "express"
 import { RateLimiterRedis, RateLimiterMemory, type RateLimiterAbstract } from "rate-limiter-flexible"
 import Redis from "ioredis"
+import { RateLimitError } from "../lib/errors.js"
 
 /**
  * Reads rate limit config from environment variables with sensible defaults.
@@ -82,7 +83,8 @@ function setRateLimitHeaders(
 
 /**
  * Express middleware: enforces per-IP rate limiting.
- * Returns 429 with a Retry-After header when the limit is exceeded.
+ * Returns 429 (standard error envelope, `details.retryAfter`) with a
+ * Retry-After header when the limit is exceeded.
  * On every response (success or 429) attaches:
  *   X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
  */
@@ -110,9 +112,6 @@ export function rateLimitMiddleware(
       const retrySecs = Math.ceil((rateLimiterRes?.msBeforeNext ?? 1000) / 1000)
       setRateLimitHeaders(res, points, 0, rateLimiterRes?.msBeforeNext ?? 1000)
       res.set("Retry-After", String(retrySecs))
-      res.status(429).json({
-        error: "Too many requests. Please retry after the indicated number of seconds.",
-        retryAfter: retrySecs,
-      })
+      next(new RateLimitError(retrySecs))
     })
 }
diff --git a/comebackhere-backend/src/middleware/validate.ts b/comebackhere-backend/src/middleware/validate.ts
index b78c7d4..2cee7f0 100644
--- a/comebackhere-backend/src/middleware/validate.ts
+++ b/comebackhere-backend/src/middleware/validate.ts
@@ -1,19 +1,20 @@
 import { z } from "zod"
 import type { Request, Response, NextFunction } from "express"
+import { ValidationError } from "../lib/errors.js"
 
 type RequestPart = "body" | "params" | "query"
 
 function makeValidator(part: RequestPart) {
   return (schema: z.ZodTypeAny) =>
-    (req: Request, res: Response, next: NextFunction) => {
+    (req: Request, _res: Response, next: NextFunction) => {
       const result = schema.safeParse(req[part])
       if (!result.success) {
         const details = result.error.issues.map((issue) => ({
           field: issue.path.join("."),
           message: issue.message,
         }))
-        const error = details.map((d) => `${d.field}: ${d.message}`).join("; ")
-        res.status(400).json({ error, details })
+        const message = details.map((d) => `${d.field}: ${d.message}`).join("; ")
+        next(new ValidationError(message, details))
         return
       }
       if (part === "body") {
diff --git a/comebackhere-backend/src/openapi.ts b/comebackhere-backend/src/openapi.ts
index 625b4fa..4a8715c 100644
--- a/comebackhere-backend/src/openapi.ts
+++ b/comebackhere-backend/src/openapi.ts
@@ -33,8 +33,29 @@ const options: swaggerJsdoc.Options = {
       schemas: {
         ErrorResponse: {
           type: "object",
+          description: "Standard error envelope returned by every endpoint.",
           properties: {
-            error: { type: "string", example: "Human-readable description of the error." },
+            error: {
+              type: "object",
+              properties: {
+                code: { type: "string", example: "VALIDATION_ERROR", description: "Stable machine-readable error code." },
+                message: { type: "string", example: "settlement_id: Must be a positive integer" },
+                details: {
+                  nullable: true,
+                  description:
+                    "Extra context. For VALIDATION_ERROR: an array of { field, message }. " +
+                    "For CONTRACT_ERROR: { contractCode }. For RATE_LIMITED: { retryAfter }. Otherwise usually null.",
+                  example: [{ field: "settlement_id", message: "Must be a positive integer" }],
+                },
+                correlationId: {
+                  type: "string",
+                  nullable: true,
+                  description: "Same value as the X-Request-Id response header.",
+                  example: "5f1c9a8e-2b7d-4c1e-9a3f-0d2e6b7c8a91",
+                },
+              },
+              required: ["code", "message", "details", "correlationId"],
+            },
           },
           required: ["error"],
         },
diff --git a/comebackhere-backend/src/routes/analytics.ts b/comebackhere-backend/src/routes/analytics.ts
index 61f0ee8..830ae1c 100644
--- a/comebackhere-backend/src/routes/analytics.ts
+++ b/comebackhere-backend/src/routes/analytics.ts
@@ -1,6 +1,7 @@
 import { Router, type Request, type Response } from "express"
 import { connectMongo, getInvoicesCollection } from "../db/mongo.js"
 import { validateQuery } from "../middleware/validate.js"
+import { asyncHandler } from "../lib/errors.js"
 import { analyticsQuerySchema } from "../schemas/index.js"
 
 const router = Router()
@@ -223,6 +224,8 @@ router.get("/metrics", validateQuery(analyticsQuerySchema), async (req: Request,
     console.error("Error fetching analytics metrics:", error)
     res.status(500).json({ error: "Failed to fetch analytics metrics" })
   }
-})
+
+  res.json(analyticsData)
+}))
 
 export default router
diff --git a/comebackhere-backend/src/routes/compliance.ts b/comebackhere-backend/src/routes/compliance.ts
index 737d054..b4e8496 100644
--- a/comebackhere-backend/src/routes/compliance.ts
+++ b/comebackhere-backend/src/routes/compliance.ts
@@ -8,6 +8,8 @@ import {
   SorobanRpc,
 } from "stellar-sdk"
 import { validateBody, validateQuery } from "../middleware/validate.js"
+import { requireEnv } from "../lib/env.js"
+import { asyncHandler, UnauthorizedError } from "../lib/errors.js"
 import { allowBodySchema, blockBodySchema, complianceAuditQuerySchema } from "../schemas/index.js"
 import { connectMongo, getComplianceAuditCollection } from "../db/mongo.js"
 
@@ -47,32 +49,27 @@ const router = Router()
  *         description: Database error
  * Returns the durable, normalized audit trail emitted by the compliance contract.
  */
-router.get("/audit", validateQuery(complianceAuditQuerySchema), async (req: Request, res: Response) => {
-  try {
-    const query = req.query as unknown as {
-      address?: string; event_type?: string; from_ledger?: number; to_ledger?: number; page: number; limit: number
-    }
-    const filter: Record<string, unknown> = {}
-    if (query.address) filter.address = query.address
-    if (query.event_type) filter.event_type = query.event_type
-    if (query.from_ledger !== undefined || query.to_ledger !== undefined) {
-      filter.ledger = {
-        ...(query.from_ledger !== undefined ? { $gte: query.from_ledger } : {}),
-        ...(query.to_ledger !== undefined ? { $lte: query.to_ledger } : {}),
-      }
+router.get("/audit", validateQuery(complianceAuditQuerySchema), asyncHandler(async (req: Request, res: Response) => {
+  const query = req.query as unknown as {
+    address?: string; event_type?: string; from_ledger?: number; to_ledger?: number; page: number; limit: number
+  }
+  const filter: Record<string, unknown> = {}
+  if (query.address) filter.address = query.address
+  if (query.event_type) filter.event_type = query.event_type
+  if (query.from_ledger !== undefined || query.to_ledger !== undefined) {
+    filter.ledger = {
+      ...(query.from_ledger !== undefined ? { $gte: query.from_ledger } : {}),
+      ...(query.to_ledger !== undefined ? { $lte: query.to_ledger } : {}),
     }
-    const skip = (query.page - 1) * query.limit
-    const collection = getComplianceAuditCollection(await connectMongo())
-    const [events, total] = await Promise.all([
-      collection.find(filter).sort({ ledger: -1, _id: -1 }).skip(skip).limit(query.limit).toArray(),
-      collection.countDocuments(filter),
-    ])
-    res.json({ events, page: query.page, limit: query.limit, total, has_more: skip + events.length < total })
-  } catch (err: unknown) {
-    const status = (err as any)?.status ?? 500
-    res.status(status).json({ error: err instanceof Error ? err.message : String(err) })
   }
-})
+  const skip = (query.page - 1) * query.limit
+  const collection = getComplianceAuditCollection(await connectMongo())
+  const [events, total] = await Promise.all([
+    collection.find(filter).sort({ ledger: -1, _id: -1 }).skip(skip).limit(query.limit).toArray(),
+    collection.countDocuments(filter),
+  ])
+  res.json({ events, page: query.page, limit: query.limit, total, has_more: skip + events.length < total })
+}))
 
 // ---------------------------------------------------------------------------
 // Shared Soroban client type — mirrors invoices.ts convention
@@ -181,43 +178,35 @@ export interface AllowBody {
  * Body: { address: string, until?: number }
  * Returns: { address, status, hash }
  */
-router.post("/allow", validateBody(allowBodySchema), async (req: Request, res: Response) => {
+router.post("/allow", validateBody(allowBodySchema), asyncHandler(async (req: Request, res: Response) => {
   const adminKey = req.headers["x-admin-key"]
   if (!adminKey || adminKey !== process.env.ADMIN_KEY) {
-    res.status(401).json({ error: "Unauthorized" })
-    return
+    throw new UnauthorizedError()
   }
 
   const { address, until } = req.body as { address: string; until?: number }
 
-  const env = requireEnv(res, {
+  const env = requireEnv({
     complianceContractId: "COMPLIANCE_CONTRACT_ID",
     signerSecret: "SIGNER_SECRET_KEY",
   })
-  if (!env) return
 
-  try {
-    const client = buildSorobanClient(env.rpcUrl)
-    const operation = until ? "allow_address_until" : "allow_address"
-    const args = until
-      ? [nativeToScVal(address, { type: "address" }), nativeToScVal(until, { type: "u64" })]
-      : [nativeToScVal(address, { type: "address" })]
-
-    const result = await callComplianceOp(
-      operation as "allow_address" | "allow_address_until",
-      args,
-      client,
-      env.complianceContractId,
-      env.signerSecret,
-      env.networkPassphrase
-    )
-    res.status(200).json(result)
-  } catch (err: unknown) {
-    const status = (err as any)?.status ?? 500
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(status).json({ error: message })
-  }
-})
+  const client = buildSorobanClient(env.rpcUrl)
+  const operation = until ? "allow_address_until" : "allow_address"
+  const args = until
+    ? [nativeToScVal(address, { type: "address" }), nativeToScVal(until, { type: "u64" })]
+    : [nativeToScVal(address, { type: "address" })]
+
+  const result = await callComplianceOp(
+    operation as "allow_address" | "allow_address_until",
+    args,
+    client,
+    env.complianceContractId,
+    env.signerSecret,
+    env.networkPassphrase
+  )
+  res.status(200).json(result)
+}))
 
 // ---------------------------------------------------------------------------
 // POST /compliance/block  (#68)
@@ -233,40 +222,32 @@ export interface BlockBody {
  * Body: { address: string }
  * Returns: { address, status, hash }
  */
-router.post("/block", validateBody(blockBodySchema), async (req: Request, res: Response) => {
+router.post("/block", validateBody(blockBodySchema), asyncHandler(async (req: Request, res: Response) => {
   const adminKey = req.headers["x-admin-key"]
   if (!adminKey || adminKey !== process.env.ADMIN_KEY) {
-    res.status(401).json({ error: "Unauthorized" })
-    return
+    throw new UnauthorizedError()
   }
 
   const { address } = req.body as { address: string }
 
-  const env = requireEnv(res, {
+  const env = requireEnv({
     complianceContractId: "COMPLIANCE_CONTRACT_ID",
     signerSecret: "SIGNER_SECRET_KEY",
   })
-  if (!env) return
 
   // Audit log — admin identity + timestamp
   console.log(`[compliance] block_address admin="${adminKey}" address="${address}" ts="${new Date().toISOString()}"`)
 
-  try {
-    const client = buildSorobanClient(env.rpcUrl)
-    const result = await callComplianceOp(
-      "block_address",
-      [nativeToScVal(address, { type: "address" })],
-      client,
-      env.complianceContractId,
-      env.signerSecret,
-      env.networkPassphrase
-    )
-    res.status(200).json(result)
-  } catch (err: unknown) {
-    const status = (err as any)?.status ?? 500
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(status).json({ error: message })
-  }
-})
+  const client = buildSorobanClient(env.rpcUrl)
+  const result = await callComplianceOp(
+    "block_address",
+    [nativeToScVal(address, { type: "address" })],
+    client,
+    env.complianceContractId,
+    env.signerSecret,
+    env.networkPassphrase
+  )
+  res.status(200).json(result)
+}))
 
 export default router
diff --git a/comebackhere-backend/src/routes/disputes.ts b/comebackhere-backend/src/routes/disputes.ts
index f992444..1cf3882 100644
--- a/comebackhere-backend/src/routes/disputes.ts
+++ b/comebackhere-backend/src/routes/disputes.ts
@@ -1,23 +1,312 @@
 import { Router, type Request, type Response } from "express"
 import { requireEnv } from "../lib/env.js"
-import { validateBody } from "../middleware/validate.js"
-import { voteBodySchema, createDisputeSchema } from "../schemas/index.js"
+import { asyncHandler, ConflictError, NotFoundError, UnauthorizedError } from "../lib/errors.js"
+import { validateBody, validateQuery } from "../middleware/validate.js"
+import {
+  voteBodySchema,
+  createDisputeSchema,
+  disputeListQuerySchema,
+  type disputeStatuses,
+} from "../schemas/index.js"
 
 const router = Router()
 
-// In-memory vote store (keyed by dispute id)
-// Shape: { [disputeId]: { votes: Map<signer, vote>, claimant_weight: number, counterparty_weight: number, outcome: string | null } }
-interface DisputeVoteState {
-  votes: Map<string, string>
+type VoteValue = "ResolvedClaimant" | "ResolvedCounterparty"
+type DisputeStatus = (typeof disputeStatuses)[number]
+
+interface DisputeVote {
+  signer: string
+  vote: VoteValue
+  weight: number
+  voted_at: Date
+}
+
+// In-memory dispute store (keyed by dispute id). Votes are kept in insertion
+// order so the admin view lists them chronologically.
+interface DisputeRecord {
+  dispute_id: string
+  settlement_id: string
+  claimant_address: string
+  reason: string | null
+  created_at: Date
+  resolved_at: Date | null
+  votes: Map<string, DisputeVote>
   claimant_weight: number
   counterparty_weight: number
-  outcome: string | null
+  outcome: VoteValue | null
+}
+const disputes = new Map<string, DisputeRecord>()
+
+/** Clears every stored dispute — used by tests for isolation. */
+export function _resetDisputeStore(): void {
+  disputes.clear()
 }
-const disputeVotes = new Map<string, DisputeVoteState>()
 
 const VOTE_THRESHOLD = Number(process.env.DISPUTE_VOTE_THRESHOLD ?? 2)
 
-type VoteValue = "ResolvedClaimant" | "ResolvedCounterparty"
+function statusOf(record: DisputeRecord): DisputeStatus {
+  return record.outcome === null ? "Raised" : "Resolved"
+}
+
+function getDisputeOrThrow(id: string): DisputeRecord {
+  const record = disputes.get(id)
+  if (!record) throw new NotFoundError(`Dispute ${id} not found`)
+  return record
+}
+
+/**
+ * Voter identities are only visible to admins (valid `x-admin-key`).
+ *
+ * Everyone else sees the tallies and vote count but not who voted which way:
+ * signers are treasury multi-sig keys, and publishing each key's vote makes it
+ * easy to single out and pressure individual signers. A wrong key is a 401
+ * rather than a silent downgrade, so misconfigured admin clients notice.
+ */
+function canSeeVoters(req: Request): boolean {
+  const adminKey = req.headers["x-admin-key"]
+  if (adminKey === undefined) return false
+  if (!process.env.ADMIN_KEY || adminKey !== process.env.ADMIN_KEY) {
+    throw new UnauthorizedError()
+  }
+  return true
+}
+
+function serializeDispute(record: DisputeRecord, includeVoters: boolean) {
+  const base = {
+    dispute_id: record.dispute_id,
+    settlement_id: record.settlement_id,
+    claimant_address: record.claimant_address,
+    reason: record.reason,
+    status: statusOf(record),
+    outcome: record.outcome,
+    claimant_weight: record.claimant_weight,
+    counterparty_weight: record.counterparty_weight,
+    resolution_weight: record.claimant_weight + record.counterparty_weight,
+    threshold: VOTE_THRESHOLD,
+    vote_count: record.votes.size,
+    created_at: record.created_at.toISOString(),
+    resolved_at: record.resolved_at?.toISOString() ?? null,
+  }
+  if (!includeVoters) return base
+  return {
+    ...base,
+    votes: [...record.votes.values()].map((v) => ({
+      signer: v.signer,
+      vote: v.vote,
+      weight: v.weight,
+      voted_at: v.voted_at.toISOString(),
+    })),
+  }
+}
+
+/**
+ * @openapi
+ * components:
+ *   schemas:
+ *     DisputeStatus:
+ *       type: string
+ *       enum: [Raised, Resolved]
+ *     DisputeVote:
+ *       type: object
+ *       properties:
+ *         signer:
+ *           type: string
+ *           description: Stellar public key of the voting signer
+ *         vote:
+ *           type: string
+ *           enum: [ResolvedClaimant, ResolvedCounterparty]
+ *         weight:
+ *           type: integer
+ *         voted_at:
+ *           type: string
+ *           format: date-time
+ *     Dispute:
+ *       type: object
+ *       properties:
+ *         dispute_id:
+ *           type: string
+ *           example: "5-1720000000000"
+ *         settlement_id:
+ *           type: string
+ *           example: "5"
+ *         claimant_address:
+ *           type: string
+ *         reason:
+ *           type: string
+ *           nullable: true
+ *         status:
+ *           $ref: '#/components/schemas/DisputeStatus'
+ *         outcome:
+ *           type: string
+ *           enum: [ResolvedClaimant, ResolvedCounterparty]
+ *           nullable: true
+ *         claimant_weight:
+ *           type: integer
+ *         counterparty_weight:
+ *           type: integer
+ *         resolution_weight:
+ *           type: integer
+ *           description: claimant_weight + counterparty_weight
+ *         threshold:
+ *           type: integer
+ *           description: Weight either side needs to resolve the dispute
+ *         vote_count:
+ *           type: integer
+ *         created_at:
+ *           type: string
+ *           format: date-time
+ *         resolved_at:
+ *           type: string
+ *           format: date-time
+ *           nullable: true
+ *         votes:
+ *           type: array
+ *           description: >-
+ *             Individual votes with signer identities. Only present when the
+ *             request carries a valid x-admin-key header.
+ *           items:
+ *             $ref: '#/components/schemas/DisputeVote'
+ */
+
+/**
+ * @openapi
+ * /disputes:
+ *   get:
+ *     tags: [Disputes]
+ *     summary: List disputes with vote tallies
+ *     description: >-
+ *       Newest first. Voter identities (`votes`) are included only for admins
+ *       (valid `x-admin-key`); everyone else sees tallies and `vote_count`.
+ *     parameters:
+ *       - in: query
+ *         name: status
+ *         schema:
+ *           $ref: '#/components/schemas/DisputeStatus'
+ *       - in: query
+ *         name: settlement_id
+ *         schema:
+ *           type: string
+ *         description: Positive integer string
+ *       - in: query
+ *         name: page
+ *         schema:
+ *           type: integer
+ *           minimum: 1
+ *           default: 1
+ *       - in: query
+ *         name: limit
+ *         schema:
+ *           type: integer
+ *           minimum: 1
+ *           maximum: 100
+ *           default: 20
+ *       - in: header
+ *         name: x-admin-key
+ *         required: false
+ *         schema:
+ *           type: string
+ *         description: Include voter identities
+ *     responses:
+ *       200:
+ *         description: Paginated dispute list
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 data:
+ *                   type: array
+ *                   items:
+ *                     $ref: '#/components/schemas/Dispute'
+ *                 total:
+ *                   type: integer
+ *                 page:
+ *                   type: integer
+ *                 limit:
+ *                   type: integer
+ *                 totalPages:
+ *                   type: integer
+ *       400:
+ *         description: Invalid query parameters
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ *       401:
+ *         description: x-admin-key supplied but invalid
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
+router.get("/", validateQuery(disputeListQuerySchema), asyncHandler(async (req: Request, res: Response) => {
+  const includeVoters = canSeeVoters(req)
+  const { status, settlement_id, page, limit } = disputeListQuerySchema.parse(req.query)
+
+  const matching = [...disputes.values()]
+    .filter((d) => (status ? statusOf(d) === status : true))
+    .filter((d) => (settlement_id ? d.settlement_id === settlement_id : true))
+    .sort((a, b) => b.created_at.getTime() - a.created_at.getTime())
+
+  const total = matching.length
+  const skip = (page - 1) * limit
+
+  res.json({
+    data: matching.slice(skip, skip + limit).map((d) => serializeDispute(d, includeVoters)),
+    total,
+    page,
+    limit,
+    totalPages: Math.ceil(total / limit),
+  })
+}))
+
+/**
+ * @openapi
+ * /disputes/{id}:
+ *   get:
+ *     tags: [Disputes]
+ *     summary: Get a dispute with its votes and tallies
+ *     description: >-
+ *       Voter identities (`votes`) are included only for admins (valid
+ *       `x-admin-key`); everyone else sees tallies and `vote_count`.
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Dispute ID
+ *       - in: header
+ *         name: x-admin-key
+ *         required: false
+ *         schema:
+ *           type: string
+ *         description: Include voter identities
+ *     responses:
+ *       200:
+ *         description: Dispute found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Dispute'
+ *       401:
+ *         description: x-admin-key supplied but invalid
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ *       404:
+ *         description: Dispute not found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
+router.get("/:id", asyncHandler(async (req: Request, res: Response) => {
+  const includeVoters = canSeeVoters(req)
+  const record = getDisputeOrThrow(req.params.id)
+  res.json(serializeDispute(record, includeVoters))
+}))
 
 /**
  * @openapi
@@ -67,6 +356,10 @@ type VoteValue = "ResolvedClaimant" | "ResolvedCounterparty"
  *                   type: integer
  *                 counterparty_weight:
  *                   type: integer
+ *                 resolution_weight:
+ *                   type: integer
+ *                 threshold:
+ *                   type: integer
  *                 outcome:
  *                   type: string
  *                   nullable: true
@@ -76,6 +369,12 @@ type VoteValue = "ResolvedClaimant" | "ResolvedCounterparty"
  *           application/json:
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
+ *       404:
+ *         description: Dispute not found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
  *       409:
  *         description: Dispute already resolved or signer already voted
  *         content:
@@ -83,32 +382,25 @@ type VoteValue = "ResolvedClaimant" | "ResolvedCounterparty"
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.post("/:id/vote", validateBody(voteBodySchema), async (req: Request, res: Response) => {
+router.post("/:id/vote", validateBody(voteBodySchema), asyncHandler(async (req: Request, res: Response) => {
   const disputeId = req.params.id
   const { signer_address, vote, weight } = req.body as {
     signer_address: string
-    vote: "ResolvedClaimant" | "ResolvedCounterparty"
+    vote: VoteValue
     weight: number
   }
 
-  const state: DisputeVoteState = disputeVotes.get(disputeId) ?? {
-    votes: new Map(),
-    claimant_weight: 0,
-    counterparty_weight: 0,
-    outcome: null,
-  }
+  const state = getDisputeOrThrow(disputeId)
 
   if (state.outcome !== null) {
-    res.status(409).json({ error: "Dispute already resolved", outcome: state.outcome })
-    return
+    throw new ConflictError("Dispute already resolved", { outcome: state.outcome })
   }
 
   if (state.votes.has(signer_address)) {
-    res.status(409).json({ error: "Signer has already voted on this dispute" })
-    return
+    throw new ConflictError("Signer has already voted on this dispute")
   }
 
-  state.votes.set(signer_address, vote)
+  state.votes.set(signer_address, { signer: signer_address, vote, weight, voted_at: new Date() })
   if (vote === "ResolvedClaimant") {
     state.claimant_weight += weight
   } else {
@@ -123,8 +415,7 @@ router.post("/:id/vote", validateBody(voteBodySchema), async (req: Request, res:
   } else if (state.counterparty_weight >= threshold) {
     state.outcome = "ResolvedCounterparty"
   }
-
-  disputeVotes.set(disputeId, state)
+  if (state.outcome !== null) state.resolved_at = new Date()
 
   res.status(200).json({
     dispute_id: disputeId,
@@ -136,7 +427,7 @@ router.post("/:id/vote", validateBody(voteBodySchema), async (req: Request, res:
     threshold,
     outcome: state.outcome,
   })
-})
+}))
 
 export interface CreateDisputeBody {
   /** Stellar public key of the party raising the dispute (claimant). */
@@ -206,32 +497,41 @@ export interface CreateDisputeBody {
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.post("/", validateBody(createDisputeSchema), async (req: Request, res: Response) => {
+router.post("/", validateBody(createDisputeSchema), asyncHandler(async (req: Request, res: Response) => {
   const body = req.body as CreateDisputeBody
 
-  if (!requireEnv(res, { settlementContractId: "SETTLEMENT_CONTRACT_ID", signerSecret: "SIGNER_SECRET_KEY" })) return
+  requireEnv({ settlementContractId: "SETTLEMENT_CONTRACT_ID", signerSecret: "SIGNER_SECRET_KEY" })
 
   const settlementId = body.settlement_id
   const claimantAddress = body.claimant_address
 
-  try {
-    // In production this would call raise_dispute on the settlement contract via Soroban RPC.
-    // The contract transitions the settlement to OnHold atomically. Here we return the
-    // expected shape so downstream clients can integrate without a live node.
-    const disputeId = `${settlementId}-${Date.now()}`
-
-    res.status(201).json({
-      dispute_id: disputeId,
-      settlement_id: settlementId,
-      claimant_address: claimantAddress,
-      status: "Raised",
-      settlement_status: "OnHold",
-    })
-  } catch (err: unknown) {
-    const status = (err as any)?.status ?? 500
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(status).json({ error: message })
-  }
-})
+  // In production this would call raise_dispute on the settlement contract via Soroban RPC.
+  // The contract transitions the settlement to OnHold atomically. Here we return the
+  // expected shape so downstream clients can integrate without a live node.
+  let createdAt = Date.now()
+  while (disputes.has(`${settlementId}-${createdAt}`)) createdAt++
+  const disputeId = `${settlementId}-${createdAt}`
+
+  disputes.set(disputeId, {
+    dispute_id: disputeId,
+    settlement_id: settlementId,
+    claimant_address: claimantAddress,
+    reason: body.reason ?? null,
+    created_at: new Date(createdAt),
+    resolved_at: null,
+    votes: new Map(),
+    claimant_weight: 0,
+    counterparty_weight: 0,
+    outcome: null,
+  })
+
+  res.status(201).json({
+    dispute_id: disputeId,
+    settlement_id: settlementId,
+    claimant_address: claimantAddress,
+    status: "Raised",
+    settlement_status: "OnHold",
+  })
+}))
 
 export default router
diff --git a/comebackhere-backend/src/routes/invoice-settings.ts b/comebackhere-backend/src/routes/invoice-settings.ts
index ba5bb31..04edee1 100644
--- a/comebackhere-backend/src/routes/invoice-settings.ts
+++ b/comebackhere-backend/src/routes/invoice-settings.ts
@@ -7,6 +7,7 @@ import {
   type SorobanClient,
 } from "../lib/soroban.js"
 import { requireEnv } from "../lib/env.js"
+import { asyncHandler } from "../lib/errors.js"
 import { validateBody } from "../middleware/validate.js"
 import { graceWindowSchema } from "../schemas/index.js"
 
@@ -36,32 +37,25 @@ const router = Router()
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.get("/grace-window", async (_req: Request, res: Response) => {
-  const env = requireEnv(res, {
+router.get("/grace-window", asyncHandler(async (_req: Request, res: Response) => {
+  const env = requireEnv({
     invoiceContractId: "INVOICE_CONTRACT_ID",
     signerSecret: "SIGNER_SECRET_KEY",
   })
-  if (!env) return
 
-  try {
-    const client = buildSorobanClient(env.rpcUrl)
-    const sourceAccount = Keypair.fromSecret(env.signerSecret).publicKey()
-    const retval = await simulateContractRead(
-      client,
-      env.invoiceContractId,
-      "get_grace_window",
-      [],
-      sourceAccount,
-      env.networkPassphrase,
-    )
-    const seconds = Number(retval.u64()?.toString() ?? "86400")
-    res.json({ grace_window_seconds: seconds })
-  } catch (err: unknown) {
-    const status = (err as { status?: number })?.status ?? 500
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(status).json({ error: message })
-  }
-})
+  const client = buildSorobanClient(env.rpcUrl)
+  const sourceAccount = Keypair.fromSecret(env.signerSecret).publicKey()
+  const retval = await simulateContractRead(
+    client,
+    env.invoiceContractId,
+    "get_grace_window",
+    [],
+    sourceAccount,
+    env.networkPassphrase,
+  )
+  const seconds = Number(retval.u64()?.toString() ?? "86400")
+  res.json({ grace_window_seconds: seconds })
+}))
 
 /**
  * POST /api/invoice/grace-window
@@ -142,23 +136,16 @@ export async function setGraceWindow(
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.post("/grace-window", validateBody(graceWindowSchema), async (req: Request, res: Response) => {
-  const env = requireEnv(res, {
+router.post("/grace-window", validateBody(graceWindowSchema), asyncHandler(async (req: Request, res: Response) => {
+  const env = requireEnv({
     invoiceContractId: "INVOICE_CONTRACT_ID",
     signerSecret: "SIGNER_SECRET_KEY",
   })
-  if (!env) return
 
   const graceWindowSeconds = req.body.grace_window_seconds
 
-  try {
-    const result = await setGraceWindow(graceWindowSeconds, env)
-    res.json(result)
-  } catch (err: unknown) {
-    const status = (err as { status?: number })?.status ?? 500
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(status).json({ error: message })
-  }
-})
+  const result = await setGraceWindow(graceWindowSeconds, env)
+  res.json(result)
+}))
 
 export default router
diff --git a/comebackhere-backend/src/routes/invoices.ts b/comebackhere-backend/src/routes/invoices.ts
index 4113d10..0a9bc22 100644
--- a/comebackhere-backend/src/routes/invoices.ts
+++ b/comebackhere-backend/src/routes/invoices.ts
@@ -3,6 +3,7 @@ import type { FindCursor, WithId } from "mongodb"
 import { Keypair, TransactionBuilder, BASE_FEE, Contract, nativeToScVal, SorobanRpc, xdr } from "stellar-sdk"
 import { connectMongo, getInvoicesCollection, type InvoiceRecord, type InvoiceStatus } from "../db/mongo.js"
 import { requireEnv } from "../lib/env.js"
+import { asyncHandler, NotFoundError } from "../lib/errors.js"
 import { cacheGet, cacheSet } from "../lib/cache.js"
 import { validateBody, validateParams } from "../middleware/validate.js"
 import { createInvoiceSchema, invoiceIdParamSchema } from "../schemas/index.js"
@@ -357,7 +358,7 @@ router.get("/export.csv", async (req: Request, res: Response) => {
  *                 totalPages:
  *                   type: integer
  */
-router.get("/", async (req: Request, res: Response) => {
+router.get("/", asyncHandler(async (req: Request, res: Response) => {
   const page = Math.max(1, parseInt(req.query.page as string, 10) || 1)
   const limit = Math.min(100, Math.max(1, parseInt(req.query.limit as string, 10) || 20))
   const { status, merchant: merchantFilter } = parseListFilters(req.query)
@@ -401,7 +402,10 @@ router.get("/", async (req: Request, res: Response) => {
     const message = err instanceof Error ? err.message : String(err)
     res.status(500).json({ error: message })
   }
-})
+
+  await cacheSet(cacheKey, result, 30)
+  res.json(result)
+}))
 
 /**
  * @openapi
@@ -448,43 +452,35 @@ router.get("/", async (req: Request, res: Response) => {
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.get("/:id", validateParams(invoiceIdParamSchema), async (req: Request, res: Response) => {
+router.get("/:id", validateParams(invoiceIdParamSchema), asyncHandler(async (req: Request, res: Response) => {
   const { id } = req.params
 
-  const env = requireEnv(res, { invoiceContractId: "INVOICE_CONTRACT_ID" })
-  if (!env) return
+  const env = requireEnv({ invoiceContractId: "INVOICE_CONTRACT_ID" })
 
-  try {
-    const server = new SorobanRpc.Server(env.rpcUrl)
-    const contract = new Contract(env.invoiceContractId)
-
-    // Build a read-only ledger entry query for the invoice
-    const ledgerKey = contract.getFootprint()
-    void ledgerKey // used below via getLedgerEntries
-
-    // Query the contract's ledger entry directly
-    const entries = await server.getLedgerEntries(
-      xdr.LedgerKey.contractData(
-        new xdr.LedgerKeyContractData({
-          contract: new Contract(env.invoiceContractId).address().toScAddress(),
-          key: nativeToScVal(BigInt(id), { type: "u64" }),
-          durability: xdr.ContractDataDurability.persistent(),
-        })
-      )
-    )
+  const server = new SorobanRpc.Server(env.rpcUrl)
+  const contract = new Contract(env.invoiceContractId)
 
-    if (!entries.entries.length) {
-      res.status(404).json({ error: "Invoice not found" })
-      return
-    }
+  // Build a read-only ledger entry query for the invoice
+  const ledgerKey = contract.getFootprint()
+  void ledgerKey // used below via getLedgerEntries
 
-    res.json({ invoice_id: id, status: "Pending" })
-  } catch (err: unknown) {
-    const status = (err as any)?.status ?? 500
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(status).json({ error: message })
+  // Query the contract's ledger entry directly
+  const entries = await server.getLedgerEntries(
+    xdr.LedgerKey.contractData(
+      new xdr.LedgerKeyContractData({
+        contract: new Contract(env.invoiceContractId).address().toScAddress(),
+        key: nativeToScVal(BigInt(id), { type: "u64" }),
+        durability: xdr.ContractDataDurability.persistent(),
+      })
+    )
+  )
+
+  if (!entries.entries.length) {
+    throw new NotFoundError("Invoice not found")
   }
-})
+
+  res.json({ invoice_id: id, status: "Pending" })
+}))
 
 /**
  * @openapi
@@ -558,45 +554,38 @@ router.get("/:id", validateParams(invoiceIdParamSchema), async (req: Request, re
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.post("/", validateBody(createInvoiceSchema), async (req: Request, res: Response) => {
-  const env = requireEnv(res, {
+router.post("/", validateBody(createInvoiceSchema), asyncHandler(async (req: Request, res: Response) => {
+  const env = requireEnv({
     invoiceContractId: "INVOICE_CONTRACT_ID",
     signerSecret: "SIGNER_SECRET_KEY",
   })
-  if (!env) return
 
-  try {
-    const client = buildSorobanClient(env.rpcUrl)
-    const result = await createInvoice(
-      req.body as CreateInvoiceBody,
-      client,
-      env.invoiceContractId,
-      env.signerSecret,
-      env.networkPassphrase
-    )
+  const client = buildSorobanClient(env.rpcUrl)
+  const result = await createInvoice(
+    req.body as CreateInvoiceBody,
+    client,
+    env.invoiceContractId,
+    env.signerSecret,
+    env.networkPassphrase
+  )
+
+  const db = await connectMongo()
+  const collection = getInvoicesCollection(db)
+  const body = req.body as CreateInvoiceBody
+  const now = new Date()
+  await collection.insertOne({
+    invoice_id: result.invoice_id,
+    merchant_address: body.merchant_address,
+    token: body.token,
+    amount: body.amount,
+    due_date: body.due_date,
+    reference: body.reference,
+    status: "Pending",
+    created_at: now,
+    updated_at: now,
+  })
 
-    const db = await connectMongo()
-    const collection = getInvoicesCollection(db)
-    const body = req.body as CreateInvoiceBody
-    const now = new Date()
-    await collection.insertOne({
-      invoice_id: result.invoice_id,
-      merchant_address: body.merchant_address,
-      token: body.token,
-      amount: body.amount,
-      due_date: body.due_date,
-      reference: body.reference,
-      status: "Pending",
-      created_at: now,
-      updated_at: now,
-    })
-
-    res.status(201).json(result)
-  } catch (err: unknown) {
-    const status = (err as any)?.status ?? 500
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(status).json({ error: message })
-  }
-})
+  res.status(201).json(result)
+}))
 
 export default router
diff --git a/comebackhere-backend/src/routes/release-escrow.ts b/comebackhere-backend/src/routes/release-escrow.ts
index 1b8d37e..1fef979 100644
--- a/comebackhere-backend/src/routes/release-escrow.ts
+++ b/comebackhere-backend/src/routes/release-escrow.ts
@@ -6,6 +6,7 @@ import {
   type SorobanClient,
 } from "../lib/soroban.js"
 import { requireEnv } from "../lib/env.js"
+import { asyncHandler, ContractError, parseContractErrorCode, UnauthorizedError } from "../lib/errors.js"
 import { validateBody, validateParams } from "../middleware/validate.js"
 import { releaseEscrowIdParamSchema } from "../schemas/index.js"
 
@@ -70,22 +71,20 @@ export async function releaseEscrow(
  *   503  required environment variables missing
  *   5xx  unexpected Soroban / network error
  */
-router.post("/:id/release-escrow", validateParams(releaseEscrowIdParamSchema), async (req: Request, res: Response) => {
+router.post("/:id/release-escrow", validateParams(releaseEscrowIdParamSchema), asyncHandler(async (req: Request, res: Response) => {
   // Admin-only authorization
   const adminKey = req.headers["x-admin-key"]
   if (!adminKey || adminKey !== process.env.ADMIN_KEY) {
-    res.status(401).json({ error: "Unauthorized" })
-    return
+    throw new UnauthorizedError()
   }
 
   const { id } = req.params
 
   const invoiceId = parseInt(id, 10)
-  const env = requireEnv(res, {
+  const env = requireEnv({
     invoiceContractId: "INVOICE_CONTRACT_ID",
     signerSecret: "SIGNER_SECRET_KEY",
   })
-  if (!env) return
 
   try {
     const result = await releaseEscrow(invoiceId, env)
@@ -94,14 +93,11 @@ router.post("/:id/release-escrow", validateParams(releaseEscrowIdParamSchema), a
     const message = err instanceof Error ? err.message : String(err)
 
     // Contract error Unauthorized = 1 → 403
-    if (message.includes("Error(Contract, #1)") || message.toUpperCase().includes("UNAUTHORIZED")) {
-      res.status(403).json({ error: "Forbidden: caller is not authorised to release this escrow", code: 1 })
-      return
+    if (parseContractErrorCode(message) === 1 || message.toUpperCase().includes("UNAUTHORIZED")) {
+      throw new ContractError(1, "Forbidden: caller is not authorised to release this escrow", 403)
     }
-
-    const status = (err as { status?: number })?.status ?? 500
-    res.status(status).json({ error: message })
+    throw err
   }
-})
+}))
 
 export default router
diff --git a/comebackhere-backend/src/routes/threshold.ts b/comebackhere-backend/src/routes/threshold.ts
index 76c4d74..c408ef2 100644
--- a/comebackhere-backend/src/routes/threshold.ts
+++ b/comebackhere-backend/src/routes/threshold.ts
@@ -7,6 +7,7 @@ import {
   type SorobanClient,
 } from "../lib/soroban.js"
 import { requireEnv } from "../lib/env.js"
+import { asyncHandler } from "../lib/errors.js"
 import { validateBody } from "../middleware/validate.js"
 import { thresholdSchema } from "../schemas/index.js"
 
@@ -16,32 +17,25 @@ const router = Router()
  * GET /api/treasury/threshold
  * Returns the current approval threshold from the treasury contract.
  */
-router.get("/threshold", async (_req: Request, res: Response) => {
-  const env = requireEnv(res, {
+router.get("/threshold", asyncHandler(async (_req: Request, res: Response) => {
+  const env = requireEnv({
     treasuryContractId: "TREASURY_CONTRACT_ID",
     signerSecret: "SIGNER_SECRET_KEY",
   })
-  if (!env) return
 
-  try {
-    const client = buildSorobanClient(env.rpcUrl)
-    const sourceAccount = Keypair.fromSecret(env.signerSecret).publicKey()
-    const retval = await simulateContractRead(
-      client,
-      env.treasuryContractId,
-      "get_threshold",
-      [],
-      sourceAccount,
-      env.networkPassphrase,
-    )
-    const threshold = Number(retval.u64()?.toString() ?? "0")
-    res.json({ threshold })
-  } catch (err: unknown) {
-    const status = (err as { status?: number })?.status ?? 500
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(status).json({ error: message })
-  }
-})
+  const client = buildSorobanClient(env.rpcUrl)
+  const sourceAccount = Keypair.fromSecret(env.signerSecret).publicKey()
+  const retval = await simulateContractRead(
+    client,
+    env.treasuryContractId,
+    "get_threshold",
+    [],
+    sourceAccount,
+    env.networkPassphrase,
+  )
+  const threshold = Number(retval.u64()?.toString() ?? "0")
+  res.json({ threshold })
+}))
 
 /**
  * POST /api/treasury/threshold
@@ -76,23 +70,16 @@ export async function setThreshold(
   return { threshold, tx_hash: txHash }
 }
 
-router.post("/threshold", validateBody(thresholdSchema), async (req: Request, res: Response) => {
-  const env = requireEnv(res, {
+router.post("/threshold", validateBody(thresholdSchema), asyncHandler(async (req: Request, res: Response) => {
+  const env = requireEnv({
     treasuryContractId: "TREASURY_CONTRACT_ID",
     signerSecret: "SIGNER_SECRET_KEY",
   })
-  if (!env) return
 
   const threshold = req.body.threshold
 
-  try {
-    const result = await setThreshold(threshold, env)
-    res.json(result)
-  } catch (err: unknown) {
-    const status = (err as { status?: number })?.status ?? 500
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(status).json({ error: message })
-  }
-})
+  const result = await setThreshold(threshold, env)
+  res.json(result)
+}))
 
 export default router
diff --git a/comebackhere-backend/src/routes/treasury.ts b/comebackhere-backend/src/routes/treasury.ts
index 0768238..a7091df 100644
--- a/comebackhere-backend/src/routes/treasury.ts
+++ b/comebackhere-backend/src/routes/treasury.ts
@@ -9,6 +9,7 @@ import {
   type SorobanClient,
 } from "../lib/soroban.js"
 import { requireEnv } from "../lib/env.js"
+import { asyncHandler, NotFoundError } from "../lib/errors.js"
 import { connectMongo, getSettlementsCollection } from "../db/mongo.js"
 import { validateBody } from "../middleware/validate.js"
 import {
@@ -46,31 +47,26 @@ export { getBalanceCache, setBalanceCache, invalidateBalanceCache }
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.get("/pending-settlements", async (_req: Request, res: Response) => {
-  try {
-    const database = await connectMongo()
-    const settlements = getSettlementsCollection(database)
-    const records = await settlements
-      .find({ status: "Pending" })
-      .sort({ id: 1 })
-      .toArray()
-
-    res.json(
-      records.map((s) => ({
-        id: s.id,
-        merchant_address: s.merchant_address,
-        amount: s.amount,
-        approvals: s.approvals,
-        approval_weight: s.approval_weight,
-        status: s.status,
-        hold_reason: s.hold_reason,
-      })),
-    )
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(500).json({ error: message })
-  }
-})
+router.get("/pending-settlements", asyncHandler(async (_req: Request, res: Response) => {
+  const database = await connectMongo()
+  const settlements = getSettlementsCollection(database)
+  const records = await settlements
+    .find({ status: "Pending" })
+    .sort({ id: 1 })
+    .toArray()
+
+  res.json(
+    records.map((s) => ({
+      id: s.id,
+      merchant_address: s.merchant_address,
+      amount: s.amount,
+      approvals: s.approvals,
+      approval_weight: s.approval_weight,
+      status: s.status,
+      hold_reason: s.hold_reason,
+    })),
+  )
+}))
 
 /**
  * @openapi
@@ -110,54 +106,47 @@ router.get("/pending-settlements", async (_req: Request, res: Response) => {
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.post("/approve-settlement", validateBody(settlementIdSchema), async (req: Request, res: Response) => {
-  const env = requireEnv(res, {
+router.post("/approve-settlement", validateBody(settlementIdSchema), asyncHandler(async (req: Request, res: Response) => {
+  const env = requireEnv({
     treasuryContractId: "TREASURY_CONTRACT_ID",
     usdcContractId: "USDC_CONTRACT_ID",
     signerSecret: "SIGNER_SECRET_KEY",
   })
-  if (!env) return
 
   const settlementId = req.body.settlement_id
 
-  try {
-    const client = buildSorobanClient(env.rpcUrl)
-    const keypair = Keypair.fromSecret(env.signerSecret)
-
-    const txHash = await submitContractCall(
-      client,
-      env.treasuryContractId,
-      "approve_settlement",
-      [
-        nativeToScVal(keypair.publicKey(), { type: "address" }),
-        nativeToScVal(BigInt(settlementId), { type: "u64" }),
-      ],
-      env.signerSecret,
-      env.networkPassphrase,
-    )
+  const client = buildSorobanClient(env.rpcUrl)
+  const keypair = Keypair.fromSecret(env.signerSecret)
 
-    const database = await connectMongo()
-    const settlements = getSettlementsCollection(database)
-    const record = await settlements.findOne({ id: settlementId })
-
-    res.json(
-      record ?? {
-        id: settlementId,
-        merchant_address: "",
-        amount: "0",
-        approvals: [keypair.publicKey()],
-        approval_weight: 1,
-        status: "Pending",
-        hold_reason: null,
-        tx_hash: txHash,
-      },
-    )
-  } catch (err: unknown) {
-    const status = (err as { status?: number })?.status ?? 500
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(status).json({ error: message })
-  }
-})
+  const txHash = await submitContractCall(
+    client,
+    env.treasuryContractId,
+    "approve_settlement",
+    [
+      nativeToScVal(keypair.publicKey(), { type: "address" }),
+      nativeToScVal(BigInt(settlementId), { type: "u64" }),
+    ],
+    env.signerSecret,
+    env.networkPassphrase,
+  )
+
+  const database = await connectMongo()
+  const settlements = getSettlementsCollection(database)
+  const record = await settlements.findOne({ id: settlementId })
+
+  res.json(
+    record ?? {
+      id: settlementId,
+      merchant_address: "",
+      amount: "0",
+      approvals: [keypair.publicKey()],
+      approval_weight: 1,
+      status: "Pending",
+      hold_reason: null,
+      tx_hash: txHash,
+    },
+  )
+}))
 
 export interface ExecuteSettlementBody {
   settlement_id: number
@@ -324,13 +313,12 @@ export async function executeSettlementWithBalanceCheck(
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.post("/execute-settlement", validateBody(executeSettlementSchema), async (req: Request, res: Response) => {
-  const env = requireEnv(res, {
+router.post("/execute-settlement", validateBody(executeSettlementSchema), asyncHandler(async (req: Request, res: Response) => {
+  const env = requireEnv({
     treasuryContractId: "TREASURY_CONTRACT_ID",
     usdcContractId: "USDC_CONTRACT_ID",
     signerSecret: "SIGNER_SECRET_KEY",
   })
-  if (!env) return
 
   const { settlement_id: settlementId, token_contract } = req.body as { settlement_id: number; token_contract?: string }
 
@@ -478,21 +466,17 @@ export async function simulateSettlement(
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.post("/simulate-settlement", validateBody(settlementIdSchema), async (req: Request, res: Response) => {
-  const env = requireEnv(res)
-  if (!env) return
+router.post("/simulate-settlement", validateBody(settlementIdSchema), asyncHandler(async (req: Request, res: Response) => {
+  const env = requireEnv({
+    treasuryContractId: "TREASURY_CONTRACT_ID",
+    signerSecret: "SIGNER_SECRET_KEY",
+  })
 
   const settlementId = req.body.settlement_id
 
-  try {
-    const result = await simulateSettlement({ settlement_id: settlementId }, env)
-    res.json(result)
-  } catch (err: unknown) {
-    const status = (err as { status?: number })?.status ?? 500
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(status).json({ error: message })
-  }
-})
+  const result = await simulateSettlement({ settlement_id: settlementId }, env)
+  res.json(result)
+}))
 
 /**
  * @openapi
@@ -519,31 +503,26 @@ router.post("/simulate-settlement", validateBody(settlementIdSchema), async (req
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.get("/on-hold-settlements", async (_req: Request, res: Response) => {
-  try {
-    const database = await connectMongo()
-    const settlements = getSettlementsCollection(database)
-    const records = await settlements
-      .find({ status: "OnHold" })
-      .sort({ id: 1 })
-      .toArray()
-
-    res.json(
-      records.map((s) => ({
-        id: s.id,
-        merchant_address: s.merchant_address,
-        amount: s.amount,
-        approvals: s.approvals,
-        approval_weight: s.approval_weight,
-        status: s.status,
-        hold_reason: s.hold_reason,
-      })),
-    )
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(500).json({ error: message })
-  }
-})
+router.get("/on-hold-settlements", asyncHandler(async (_req: Request, res: Response) => {
+  const database = await connectMongo()
+  const settlements = getSettlementsCollection(database)
+  const records = await settlements
+    .find({ status: "OnHold" })
+    .sort({ id: 1 })
+    .toArray()
+
+  res.json(
+    records.map((s) => ({
+      id: s.id,
+      merchant_address: s.merchant_address,
+      amount: s.amount,
+      approvals: s.approvals,
+      approval_weight: s.approval_weight,
+      status: s.status,
+      hold_reason: s.hold_reason,
+    })),
+  )
+}))
 
 /**
  * @openapi
@@ -583,37 +562,31 @@ router.get("/on-hold-settlements", async (_req: Request, res: Response) => {
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.post("/release-hold", validateBody(settlementIdSchema), async (req: Request, res: Response) => {
+router.post("/release-hold", validateBody(settlementIdSchema), asyncHandler(async (req: Request, res: Response) => {
   const settlementId = req.body.settlement_id
 
-  try {
-    const database = await connectMongo()
-    const settlements = getSettlementsCollection(database)
-    const record = await settlements.findOneAndUpdate(
-      { id: settlementId, status: "OnHold" },
-      { $set: { status: "Pending", hold_reason: null, updated_at: new Date() } },
-      { returnDocument: "after" },
-    )
+  const database = await connectMongo()
+  const settlements = getSettlementsCollection(database)
+  const record = await settlements.findOneAndUpdate(
+    { id: settlementId, status: "OnHold" },
+    { $set: { status: "Pending", hold_reason: null, updated_at: new Date() } },
+    { returnDocument: "after" },
+  )
 
-    if (!record) {
-      res.status(404).json({ error: `Settlement #${settlementId} not found or not on hold` })
-      return
-    }
-
-    res.json({
-      id: record.id,
-      merchant_address: record.merchant_address,
-      amount: record.amount,
-      approvals: record.approvals,
-      approval_weight: record.approval_weight,
-      status: record.status,
-      hold_reason: record.hold_reason,
-    })
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(500).json({ error: message })
+  if (!record) {
+    throw new NotFoundError(`Settlement #${settlementId} not found or not on hold`)
   }
-})
+
+  res.json({
+    id: record.id,
+    merchant_address: record.merchant_address,
+    amount: record.amount,
+    approvals: record.approvals,
+    approval_weight: record.approval_weight,
+    status: record.status,
+    hold_reason: record.hold_reason,
+  })
+}))
 
 /**
  * @openapi
@@ -678,50 +651,43 @@ router.post("/release-hold", validateBody(settlementIdSchema), async (req: Reque
  *             schema:
  *               $ref: '#/components/schemas/ErrorResponse'
  */
-router.post("/escalate-hold", validateBody(escalateHoldSchema), async (req: Request, res: Response) => {
+router.post("/escalate-hold", validateBody(escalateHoldSchema), asyncHandler(async (req: Request, res: Response) => {
   const settlementId = req.body.settlement_id
 
-  try {
-    const database = await connectMongo()
-    const settlements = getSettlementsCollection(database)
-    const record = await settlements.findOneAndUpdate(
-      { id: settlementId, status: "OnHold" },
-      { $set: { hold_reason: "AdminHold", updated_at: new Date() } },
-      { returnDocument: "after" },
-    )
+  const database = await connectMongo()
+  const settlements = getSettlementsCollection(database)
+  const record = await settlements.findOneAndUpdate(
+    { id: settlementId, status: "OnHold" },
+    { $set: { hold_reason: "AdminHold", updated_at: new Date() } },
+    { returnDocument: "after" },
+  )
 
-    if (!record) {
-      res.status(404).json({ error: `Settlement #${settlementId} not found or not on hold` })
-      return
-    }
-
-    res.json({
-      id: record.id,
-      merchant_address: record.merchant_address,
-      amount: record.amount,
-      approvals: record.approvals,
-      approval_weight: record.approval_weight,
-      status: record.status,
-      hold_reason: record.hold_reason,
-    })
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(500).json({ error: message })
+  if (!record) {
+    throw new NotFoundError(`Settlement #${settlementId} not found or not on hold`)
   }
-})
+
+  res.json({
+    id: record.id,
+    merchant_address: record.merchant_address,
+    amount: record.amount,
+    approvals: record.approvals,
+    approval_weight: record.approval_weight,
+    status: record.status,
+    hold_reason: record.hold_reason,
+  })
+}))
 
 /**
  * GET /api/treasury/balances
  * Returns token balances held by the treasury contract.
  * Results are cached for up to 5 seconds to reduce Soroban RPC load (#212).
  */
-router.get("/balances", async (_req: Request, res: Response) => {
-  const env = requireEnv(res, {
+router.get("/balances", asyncHandler(async (_req: Request, res: Response) => {
+  const env = requireEnv({
     treasuryContractId: "TREASURY_CONTRACT_ID",
     usdcContractId: "USDC_CONTRACT_ID",
     signerSecret: "SIGNER_SECRET_KEY",
   })
-  if (!env) return
 
   // #212 — serve from cache when available
   const cached = getBalanceCache()
@@ -730,27 +696,21 @@ router.get("/balances", async (_req: Request, res: Response) => {
     return
   }
 
-  try {
-    const client = buildSorobanClient(env.rpcUrl)
-    const keypair = Keypair.fromSecret(env.signerSecret)
-    const sourceAccount = keypair.publicKey()
-
-    const balance = await getTokenBalance(
-      client,
-      env.usdcContractId,
-      env.treasuryContractId,
-      sourceAccount,
-      env.networkPassphrase,
-    )
+  const client = buildSorobanClient(env.rpcUrl)
+  const keypair = Keypair.fromSecret(env.signerSecret)
+  const sourceAccount = keypair.publicKey()
 
-    const data = [{ token: env.usdcContractId, balance: balance.toString() }]
-    setBalanceCache(data)
-    res.json(data)
-  } catch (err: unknown) {
-    const status = (err as { status?: number })?.status ?? 500
-    const message = err instanceof Error ? err.message : String(err)
-    res.status(status).json({ error: message })
-  }
-})
+  const balance = await getTokenBalance(
+    client,
+    env.usdcContractId,
+    env.treasuryContractId,
+    sourceAccount,
+    env.networkPassphrase,
+  )
+
+  const data = [{ token: env.usdcContractId, balance: balance.toString() }]
+  setBalanceCache(data)
+  res.json(data)
+}))
 
 export default router
diff --git a/comebackhere-backend/src/schemas/index.ts b/comebackhere-backend/src/schemas/index.ts
index 0de00c6..9ee5257 100644
--- a/comebackhere-backend/src/schemas/index.ts
+++ b/comebackhere-backend/src/schemas/index.ts
@@ -117,6 +117,23 @@ export const createDisputeSchema = z.object({
   reason: z.string().optional(),
 })
 
+export const disputeStatuses = ["Raised", "Resolved"] as const
+
+export const disputeListQuerySchema = z.object({
+  status: z.enum(disputeStatuses, { message: "status must be 'Raised' or 'Resolved'" }).optional(),
+  settlement_id: z
+    .string()
+    .regex(/^\d+$/, "settlement_id must be a positive integer string")
+    .optional(),
+  page: z.coerce.number().int("page must be a positive integer").positive("page must be a positive integer").default(1),
+  limit: z.coerce
+    .number()
+    .int("limit must be an integer between 1 and 100")
+    .positive("limit must be an integer between 1 and 100")
+    .max(100, "limit must be an integer between 1 and 100")
+    .default(20),
+})
+
 export const complianceAuditQuerySchema = z.object({
   address: stellarAddress.optional(),
   event_type: z.enum(["address_allowed", "address_allowed_until", "address_blocked", "address_cleared"]).optional(),
diff --git a/comebackhere-backend/src/tests/compliance-audit.test.ts b/comebackhere-backend/src/tests/compliance-audit.test.ts
index d7f9eae..bcaa2d0 100644
--- a/comebackhere-backend/src/tests/compliance-audit.test.ts
+++ b/comebackhere-backend/src/tests/compliance-audit.test.ts
@@ -46,7 +46,7 @@ describe("GET /compliance/audit", () => {
   it("rejects an invalid ledger range", async () => {
     const response = await request(createApp()).get("/compliance/audit").query({ from_ledger: 20, to_ledger: 10 })
     expect(response.status).toBe(400)
-    expect(response.body.error).toMatch(/from_ledger/i)
+    expect(response.body.error.message).toMatch(/from_ledger/i)
   })
 
   it("rejects a limit above the public maximum", async () => {
diff --git a/comebackhere-backend/src/tests/compliance.test.ts b/comebackhere-backend/src/tests/compliance.test.ts
index 6ac64a8..533e283 100644
--- a/comebackhere-backend/src/tests/compliance.test.ts
+++ b/comebackhere-backend/src/tests/compliance.test.ts
@@ -232,7 +232,7 @@ describe("POST /compliance/allow", () => {
       .post("/compliance/allow")
       .send({ address: VALID_ADDRESS })
     expect(res.status).toBe(401)
-    expect(res.body.error).toMatch(/unauthorized/i)
+    expect(res.body.error.message).toMatch(/unauthorized/i)
   })
 
   it("401 when x-admin-key header is wrong", async () => {
@@ -249,7 +249,7 @@ describe("POST /compliance/allow", () => {
       .set("x-admin-key", ADMIN_KEY)
       .send({})
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/address/)
+    expect(res.body.error.message).toMatch(/address/)
   })
 
   it("400 when address is not a valid Stellar public key", async () => {
@@ -258,7 +258,7 @@ describe("POST /compliance/allow", () => {
       .set("x-admin-key", ADMIN_KEY)
       .send({ address: "NOT_A_STELLAR_KEY" })
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/address/)
+    expect(res.body.error.message).toMatch(/address/)
   })
 
   it("400 when until is provided but is not a positive integer", async () => {
@@ -267,7 +267,7 @@ describe("POST /compliance/allow", () => {
       .set("x-admin-key", ADMIN_KEY)
       .send({ address: VALID_ADDRESS, until: -1 })
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/until/)
+    expect(res.body.error.message).toMatch(/until/)
   })
 
   it("503 when required env vars are missing", async () => {
@@ -277,7 +277,7 @@ describe("POST /compliance/allow", () => {
       .set("x-admin-key", ADMIN_KEY)
       .send({ address: VALID_ADDRESS })
     expect(res.status).toBe(503)
-    expect(res.body.error).toMatch(/misconfiguration/i)
+    expect(res.body.error.message).toMatch(/misconfiguration/i)
   })
 })
 
@@ -309,7 +309,7 @@ describe("POST /compliance/block", () => {
       .post("/compliance/block")
       .send({ address: VALID_ADDRESS })
     expect(res.status).toBe(401)
-    expect(res.body.error).toMatch(/unauthorized/i)
+    expect(res.body.error.message).toMatch(/unauthorized/i)
   })
 
   it("401 when x-admin-key header is wrong", async () => {
@@ -326,7 +326,7 @@ describe("POST /compliance/block", () => {
       .set("x-admin-key", ADMIN_KEY)
       .send({})
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/address/)
+    expect(res.body.error.message).toMatch(/address/)
   })
 
   it("400 when address has invalid format (e.g. G... but not a real key)", async () => {
@@ -335,7 +335,7 @@ describe("POST /compliance/block", () => {
       .set("x-admin-key", ADMIN_KEY)
       .send({ address: "GNOTAVALIDADDRESSATALL" })
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/address/)
+    expect(res.body.error.message).toMatch(/address/)
   })
 
   it("503 when required env vars are missing", async () => {
@@ -345,6 +345,6 @@ describe("POST /compliance/block", () => {
       .set("x-admin-key", ADMIN_KEY)
       .send({ address: VALID_ADDRESS })
     expect(res.status).toBe(503)
-    expect(res.body.error).toMatch(/misconfiguration/i)
+    expect(res.body.error.message).toMatch(/misconfiguration/i)
   })
 })
diff --git a/comebackhere-backend/src/tests/correlationId.test.ts b/comebackhere-backend/src/tests/correlationId.test.ts
index 3c4b23e..897b487 100644
--- a/comebackhere-backend/src/tests/correlationId.test.ts
+++ b/comebackhere-backend/src/tests/correlationId.test.ts
@@ -2,20 +2,17 @@ import { describe, it, expect } from "vitest"
 import request from "supertest"
 import { createApp } from "../app.js"
 
-// Attach a simple probe route so we can test the middleware in isolation
-// without hitting any real route logic.
+// /health has no route logic of its own, so it exercises the middleware in
+// isolation. Unknown routes fall through to the central error handler, which
+// echoes res.locals.requestId as the envelope's correlationId.
 function createTestApp() {
-  const app = createApp()
-  app.get("/probe", (_req, res) => {
-    res.status(200).json({ requestId: res.locals.requestId })
-  })
-  return app
+  return createApp()
 }
 
 describe("correlationIdMiddleware", () => {
   it("adds an X-Request-Id header to the response", async () => {
     const app = createTestApp()
-    const res = await request(app).get("/probe")
+    const res = await request(app).get("/health")
     expect(res.headers["x-request-id"]).toBeDefined()
     expect(typeof res.headers["x-request-id"]).toBe("string")
     expect(res.headers["x-request-id"].length).toBeGreaterThan(0)
@@ -23,7 +20,7 @@ describe("correlationIdMiddleware", () => {
 
   it("generates a new UUID when the client does not supply X-Request-Id", async () => {
     const app = createTestApp()
-    const res = await request(app).get("/probe")
+    const res = await request(app).get("/health")
     // UUID v4 pattern
     expect(res.headers["x-request-id"]).toMatch(
       /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
@@ -33,7 +30,7 @@ describe("correlationIdMiddleware", () => {
   it("preserves a client-supplied X-Request-Id rather than overwriting it", async () => {
     const clientId = "my-trace-id-12345"
     const app = createTestApp()
-    const res = await request(app).get("/probe").set("X-Request-Id", clientId)
+    const res = await request(app).get("/health").set("X-Request-Id", clientId)
 
     expect(res.headers["x-request-id"]).toBe(clientId)
   })
@@ -41,16 +38,17 @@ describe("correlationIdMiddleware", () => {
   it("stores the request ID in res.locals.requestId for downstream handlers", async () => {
     const clientId = "locals-check-id"
     const app = createTestApp()
-    const res = await request(app).get("/probe").set("X-Request-Id", clientId)
+    const res = await request(app).get("/does-not-exist").set("X-Request-Id", clientId)
 
-    expect(res.body.requestId).toBe(clientId)
+    expect(res.status).toBe(404)
+    expect(res.body.error.correlationId).toBe(clientId)
   })
 
   it("generates a different ID for each request when no client ID is supplied", async () => {
     const app = createTestApp()
     const [res1, res2] = await Promise.all([
-      request(app).get("/probe"),
-      request(app).get("/probe"),
+      request(app).get("/health"),
+      request(app).get("/health"),
     ])
 
     expect(res1.headers["x-request-id"]).not.toBe(res2.headers["x-request-id"])
diff --git a/comebackhere-backend/src/tests/cors.test.ts b/comebackhere-backend/src/tests/cors.test.ts
new file mode 100644
index 0000000..47e69aa
--- /dev/null
+++ b/comebackhere-backend/src/tests/cors.test.ts
@@ -0,0 +1,147 @@
+import { describe, it, expect, afterEach } from "vitest"
+import request from "supertest"
+import { createApp } from "../app.js"
+import { parseCorsOrigins } from "../lib/env.js"
+
+const ALLOWED = "http://localhost:5173"
+const ALSO_ALLOWED = "https://app.example.com"
+const BLOCKED = "https://evil.example.com"
+
+describe("CORS allowlist", () => {
+  const app = createApp({ corsOrigins: [ALLOWED, ALSO_ALLOWED] })
+
+  it("allows requests from an allowlisted origin", async () => {
+    const res = await request(app).get("/health").set("Origin", ALLOWED)
+
+    expect(res.status).toBe(200)
+    expect(res.headers["access-control-allow-origin"]).toBe(ALLOWED)
+    expect(res.headers["vary"]).toMatch(/Origin/)
+    expect(res.headers["access-control-expose-headers"]).toContain("X-Request-Id")
+  })
+
+  it("echoes the specific origin, never a wildcard", async () => {
+    const res = await request(app).get("/health").set("Origin", ALSO_ALLOWED)
+    expect(res.headers["access-control-allow-origin"]).toBe(ALSO_ALLOWED)
+  })
+
+  it("rejects requests from an unknown origin with 403 in the standard envelope", async () => {
+    const res = await request(app).get("/health").set("Origin", BLOCKED).set("X-Request-Id", "req-cors")
+
+    expect(res.status).toBe(403)
+    expect(res.headers["access-control-allow-origin"]).toBeUndefined()
+    expect(res.body).toEqual({
+      error: {
+        code: "CORS_ORIGIN_NOT_ALLOWED",
+        message: `Origin ${BLOCKED} is not allowed to access this API`,
+        details: { origin: BLOCKED },
+        correlationId: "req-cors",
+      },
+    })
+  })
+
+  it("does not treat a different port or scheme as the same origin", async () => {
+    for (const origin of ["http://localhost:3001", "https://localhost:5173"]) {
+      const res = await request(app).get("/health").set("Origin", origin)
+      expect(res.status, origin).toBe(403)
+    }
+  })
+
+  it("lets requests without an Origin header through (same-origin / server-to-server)", async () => {
+    const res = await request(app).get("/health")
+    expect(res.status).toBe(200)
+    expect(res.headers["access-control-allow-origin"]).toBeUndefined()
+  })
+
+  it("answers preflight for the headers the frontend uses", async () => {
+    const res = await request(app)
+      .options("/invoices")
+      .set("Origin", ALLOWED)
+      .set("Access-Control-Request-Method", "POST")
+      .set("Access-Control-Request-Headers", "authorization,idempotency-key,content-type")
+
+    expect(res.status).toBe(204)
+    expect(res.headers["access-control-allow-origin"]).toBe(ALLOWED)
+    expect(res.headers["access-control-allow-methods"]).toContain("POST")
+    const allowedHeaders = res.headers["access-control-allow-headers"].toLowerCase()
+    for (const header of ["authorization", "idempotency-key", "content-type", "x-request-id"]) {
+      expect(allowedHeaders).toContain(header)
+    }
+  })
+
+  it("rejects preflight from an unknown origin", async () => {
+    const res = await request(app)
+      .options("/invoices")
+      .set("Origin", BLOCKED)
+      .set("Access-Control-Request-Method", "POST")
+
+    expect(res.status).toBe(403)
+    expect(res.headers["access-control-allow-origin"]).toBeUndefined()
+    expect(res.body.error.code).toBe("CORS_ORIGIN_NOT_ALLOWED")
+  })
+
+  it("blocks every cross-origin request when the allowlist is empty", async () => {
+    const closed = createApp({ corsOrigins: [] })
+    const res = await request(closed).get("/health").set("Origin", ALLOWED)
+    expect(res.status).toBe(403)
+  })
+})
+
+describe("CORS_ORIGINS env var", () => {
+  const backup = process.env.CORS_ORIGINS
+  afterEach(() => {
+    if (backup === undefined) delete process.env.CORS_ORIGINS
+    else process.env.CORS_ORIGINS = backup
+  })
+
+  it("is read by createApp when no explicit origins are passed", async () => {
+    process.env.CORS_ORIGINS = `${ALLOWED}, ${ALSO_ALLOWED}`
+    const app = createApp()
+
+    const ok = await request(app).get("/health").set("Origin", ALSO_ALLOWED)
+    expect(ok.headers["access-control-allow-origin"]).toBe(ALSO_ALLOWED)
+
+    const blocked = await request(app).get("/health").set("Origin", BLOCKED)
+    expect(blocked.status).toBe(403)
+  })
+
+  it("makes createApp fail fast on an invalid value", () => {
+    process.env.CORS_ORIGINS = "*"
+    expect(() => createApp()).toThrow(/CORS_ORIGINS/)
+  })
+})
+
+describe("parseCorsOrigins", () => {
+  it("parses a comma-separated list, trimming whitespace and blanks", () => {
+    expect(parseCorsOrigins(" http://localhost:5173 ,, https://app.example.com ")).toEqual([
+      "http://localhost:5173",
+      "https://app.example.com",
+    ])
+  })
+
+  it("normalises case and default ports and de-duplicates", () => {
+    expect(parseCorsOrigins("https://App.Example.com,https://app.example.com:443")).toEqual([
+      "https://app.example.com",
+    ])
+  })
+
+  it("returns an empty list when unset or empty", () => {
+    expect(parseCorsOrigins(undefined)).toEqual([])
+    expect(parseCorsOrigins("")).toEqual([])
+  })
+
+  it.each([
+    ["*"],
+    ["https://*.example.com"],
+    ["app.example.com"],
+    ["ftp://example.com"],
+    ["https://app.example.com/"],
+    ["https://app.example.com/path"],
+    ["https://app.example.com?x=1"],
+  ])("rejects %s", (value) => {
+    expect(() => parseCorsOrigins(value)).toThrow(/Invalid CORS_ORIGINS/)
+  })
+
+  it("lists every invalid entry in one error", () => {
+    expect(() => parseCorsOrigins("*,https://ok.example.com,nope")).toThrow(/"\*".*"nope"/)
+  })
+})
diff --git a/comebackhere-backend/src/tests/disputes.test.ts b/comebackhere-backend/src/tests/disputes.test.ts
new file mode 100644
index 0000000..e7123ff
--- /dev/null
+++ b/comebackhere-backend/src/tests/disputes.test.ts
@@ -0,0 +1,268 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest"
+import request from "supertest"
+import { Keypair } from "stellar-sdk"
+import { createApp } from "../app.js"
+import { _resetDisputeStore } from "../routes/disputes.js"
+import { resetLimiter } from "../middleware/rateLimiter.js"
+
+const ADMIN_KEY = "test-admin-key"
+const ENV = {
+  SOROBAN_RPC_URL: "http://localhost:8000/soroban/rpc",
+  SETTLEMENT_CONTRACT_ID: "CSETTLEMENT",
+  SIGNER_SECRET_KEY: Keypair.random().secret(),
+  ADMIN_KEY,
+  // Many requests per test; keep the shared in-memory limiter out of the way
+  RATE_LIMIT_POINTS: "10000",
+}
+
+const CLAIMANT = Keypair.random().publicKey()
+const SIGNER_A = Keypair.random().publicKey()
+const SIGNER_B = Keypair.random().publicKey()
+const SIGNER_C = Keypair.random().publicKey()
+
+describe("dispute read endpoints", () => {
+  const app = createApp()
+  let envBackup: Record<string, string | undefined>
+
+  beforeEach(() => {
+    _resetDisputeStore()
+    envBackup = {}
+    for (const [key, value] of Object.entries(ENV)) {
+      envBackup[key] = process.env[key]
+      process.env[key] = value
+    }
+    resetLimiter()
+  })
+
+  afterEach(() => {
+    for (const [key, value] of Object.entries(envBackup)) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+    resetLimiter()
+  })
+
+  async function createDispute(settlementId: string, reason?: string): Promise<string> {
+    const res = await request(app)
+      .post("/disputes")
+      .send({ claimant_address: CLAIMANT, settlement_id: settlementId, reason })
+    expect(res.status).toBe(201)
+    return res.body.dispute_id
+  }
+
+  async function vote(id: string, signer: string, v: "ResolvedClaimant" | "ResolvedCounterparty", weight = 1) {
+    return request(app).post(`/disputes/${id}/vote`).send({ signer_address: signer, vote: v, weight })
+  }
+
+  describe("GET /disputes/:id", () => {
+    it("returns full details and tallies for a new dispute", async () => {
+      const id = await createDispute("5", "Goods not delivered")
+      const res = await request(app).get(`/disputes/${id}`)
+
+      expect(res.status).toBe(200)
+      expect(res.body).toMatchObject({
+        dispute_id: id,
+        settlement_id: "5",
+        claimant_address: CLAIMANT,
+        reason: "Goods not delivered",
+        status: "Raised",
+        outcome: null,
+        claimant_weight: 0,
+        counterparty_weight: 0,
+        resolution_weight: 0,
+        threshold: 2,
+        vote_count: 0,
+        resolved_at: null,
+      })
+      expect(new Date(res.body.created_at).toString()).not.toBe("Invalid Date")
+    })
+
+    it("reflects votes in the tallies", async () => {
+      const id = await createDispute("5")
+      await vote(id, SIGNER_A, "ResolvedClaimant")
+      await vote(id, SIGNER_B, "ResolvedCounterparty")
+
+      const res = await request(app).get(`/disputes/${id}`)
+      expect(res.body).toMatchObject({
+        status: "Raised",
+        claimant_weight: 1,
+        counterparty_weight: 1,
+        resolution_weight: 2,
+        vote_count: 2,
+        outcome: null,
+      })
+    })
+
+    it("marks the dispute Resolved once a side reaches the threshold", async () => {
+      const id = await createDispute("5")
+      await vote(id, SIGNER_A, "ResolvedClaimant")
+      await vote(id, SIGNER_B, "ResolvedClaimant")
+
+      const res = await request(app).get(`/disputes/${id}`)
+      expect(res.body.status).toBe("Resolved")
+      expect(res.body.outcome).toBe("ResolvedClaimant")
+      expect(res.body.resolved_at).not.toBeNull()
+    })
+
+    it("hides voter identities from non-admins", async () => {
+      const id = await createDispute("5")
+      await vote(id, SIGNER_A, "ResolvedClaimant")
+
+      const res = await request(app).get(`/disputes/${id}`)
+      expect(res.body).not.toHaveProperty("votes")
+      expect(JSON.stringify(res.body)).not.toContain(SIGNER_A)
+    })
+
+    it("shows voter identities to admins", async () => {
+      const id = await createDispute("5")
+      await vote(id, SIGNER_A, "ResolvedClaimant", 1)
+      await vote(id, SIGNER_B, "ResolvedCounterparty", 1)
+
+      const res = await request(app).get(`/disputes/${id}`).set("x-admin-key", ADMIN_KEY)
+      expect(res.status).toBe(200)
+      expect(res.body.votes).toHaveLength(2)
+      expect(res.body.votes[0]).toMatchObject({ signer: SIGNER_A, vote: "ResolvedClaimant", weight: 1 })
+      expect(res.body.votes[1]).toMatchObject({ signer: SIGNER_B, vote: "ResolvedCounterparty", weight: 1 })
+    })
+
+    it("rejects an invalid admin key with 401", async () => {
+      const id = await createDispute("5")
+      const res = await request(app).get(`/disputes/${id}`).set("x-admin-key", "wrong")
+      expect(res.status).toBe(401)
+      expect(res.body.error.code).toBe("UNAUTHORIZED")
+    })
+
+    it("returns 404 in the standard envelope for an unknown dispute", async () => {
+      const res = await request(app).get("/disputes/999-123").set("X-Request-Id", "req-404")
+      expect(res.status).toBe(404)
+      expect(res.body).toEqual({
+        error: {
+          code: "NOT_FOUND",
+          message: "Dispute 999-123 not found",
+          details: null,
+          correlationId: "req-404",
+        },
+      })
+    })
+  })
+
+  describe("GET /disputes", () => {
+    it("returns an empty page when there are no disputes", async () => {
+      const res = await request(app).get("/disputes")
+      expect(res.status).toBe(200)
+      expect(res.body).toEqual({ data: [], total: 0, page: 1, limit: 20, totalPages: 0 })
+    })
+
+    it("lists disputes newest first with tallies", async () => {
+      const first = await createDispute("1")
+      const second = await createDispute("2")
+      await vote(second, SIGNER_A, "ResolvedCounterparty")
+
+      const res = await request(app).get("/disputes")
+      expect(res.status).toBe(200)
+      expect(res.body.total).toBe(2)
+      expect(res.body.data.map((d: any) => d.dispute_id)).toEqual([second, first])
+      expect(res.body.data[0]).toMatchObject({ counterparty_weight: 1, vote_count: 1 })
+      expect(res.body.data[0]).not.toHaveProperty("votes")
+    })
+
+    it("filters by status", async () => {
+      const open = await createDispute("1")
+      const resolved = await createDispute("2")
+      await vote(resolved, SIGNER_A, "ResolvedClaimant")
+      await vote(resolved, SIGNER_B, "ResolvedClaimant")
+
+      const raised = await request(app).get("/disputes").query({ status: "Raised" })
+      expect(raised.body.data.map((d: any) => d.dispute_id)).toEqual([open])
+
+      const done = await request(app).get("/disputes").query({ status: "Resolved" })
+      expect(done.body.data.map((d: any) => d.dispute_id)).toEqual([resolved])
+    })
+
+    it("filters by settlement id", async () => {
+      await createDispute("1")
+      const target = await createDispute("7")
+      await createDispute("8")
+
+      const res = await request(app).get("/disputes").query({ settlement_id: "7" })
+      expect(res.body.total).toBe(1)
+      expect(res.body.data[0].dispute_id).toBe(target)
+    })
+
+    it("combines filters", async () => {
+      const a = await createDispute("7")
+      const b = await createDispute("7")
+      await vote(b, SIGNER_A, "ResolvedClaimant")
+      await vote(b, SIGNER_C, "ResolvedClaimant")
+      await createDispute("8")
+
+      const res = await request(app).get("/disputes").query({ settlement_id: "7", status: "Raised" })
+      expect(res.body.data.map((d: any) => d.dispute_id)).toEqual([a])
+    })
+
+    it("paginates", async () => {
+      const ids: string[] = []
+      for (let i = 1; i <= 5; i++) ids.push(await createDispute(String(i)))
+
+      const res = await request(app).get("/disputes").query({ page: 2, limit: 2 })
+      expect(res.body).toMatchObject({ total: 5, page: 2, limit: 2, totalPages: 3 })
+      expect(res.body.data.map((d: any) => d.dispute_id)).toEqual([ids[2], ids[1]])
+    })
+
+    it("includes voter identities for admins", async () => {
+      const id = await createDispute("1")
+      await vote(id, SIGNER_A, "ResolvedClaimant")
+
+      const res = await request(app).get("/disputes").set("x-admin-key", ADMIN_KEY)
+      expect(res.body.data[0].votes).toEqual([
+        expect.objectContaining({ signer: SIGNER_A, vote: "ResolvedClaimant", weight: 1 }),
+      ])
+    })
+
+    it.each([
+      [{ status: "Open" }, "status"],
+      [{ settlement_id: "abc" }, "settlement_id"],
+      [{ limit: 0 }, "limit"],
+      [{ limit: 101 }, "limit"],
+      [{ page: 0 }, "page"],
+    ])("rejects invalid query %o with a validation envelope", async (query, field) => {
+      const res = await request(app).get("/disputes").query(query)
+      expect(res.status).toBe(400)
+      expect(res.body.error.code).toBe("VALIDATION_ERROR")
+      expect(res.body.error.details[0].field).toBe(field)
+    })
+  })
+
+  describe("POST /disputes/:id/vote", () => {
+    it("returns 404 when voting on an unknown dispute", async () => {
+      const res = await vote("999-123", SIGNER_A, "ResolvedClaimant")
+      expect(res.status).toBe(404)
+      expect(res.body.error.code).toBe("NOT_FOUND")
+    })
+
+    it("returns 409 when a signer votes twice", async () => {
+      const id = await createDispute("1")
+      await vote(id, SIGNER_A, "ResolvedClaimant")
+      const res = await vote(id, SIGNER_A, "ResolvedClaimant")
+      expect(res.status).toBe(409)
+      expect(res.body.error.code).toBe("CONFLICT")
+    })
+
+    it("returns 409 with the outcome once resolved", async () => {
+      const id = await createDispute("1")
+      await vote(id, SIGNER_A, "ResolvedClaimant", 2)
+      const res = await vote(id, SIGNER_B, "ResolvedCounterparty")
+      expect(res.status).toBe(409)
+      expect(res.body.error.details).toEqual({ outcome: "ResolvedClaimant" })
+    })
+
+    it("uses the custom message for an invalid vote value", async () => {
+      const id = await createDispute("1")
+      const res = await request(app).post(`/disputes/${id}/vote`).send({ signer_address: SIGNER_A, vote: "Maybe" })
+      expect(res.status).toBe(400)
+      expect(res.body.error.details).toEqual([
+        { field: "vote", message: "vote must be 'ResolvedClaimant' or 'ResolvedCounterparty'" },
+      ])
+    })
+  })
+})
diff --git a/comebackhere-backend/src/tests/error-envelope.test.ts b/comebackhere-backend/src/tests/error-envelope.test.ts
new file mode 100644
index 0000000..a7ff89d
--- /dev/null
+++ b/comebackhere-backend/src/tests/error-envelope.test.ts
@@ -0,0 +1,102 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest"
+import request from "supertest"
+import { createApp } from "../app.js"
+import { toAppError } from "../middleware/errorHandler.js"
+import { AppError, ContractError, NotFoundError, ValidationError } from "../lib/errors.js"
+
+function expectEnvelope(body: any) {
+  expect(Object.keys(body)).toEqual(["error"])
+  expect(Object.keys(body.error).sort()).toEqual(["code", "correlationId", "details", "message"])
+  expect(typeof body.error.code).toBe("string")
+  expect(typeof body.error.message).toBe("string")
+}
+
+describe("standard error envelope", () => {
+  const app = createApp()
+
+  it("wraps zod validation failures with field-level details", async () => {
+    const res = await request(app)
+      .post("/api/treasury/threshold")
+      .set("X-Request-Id", "req-validation")
+      .send({ threshold: -1 })
+
+    expect(res.status).toBe(400)
+    expectEnvelope(res.body)
+    expect(res.body.error.code).toBe("VALIDATION_ERROR")
+    expect(res.body.error.correlationId).toBe("req-validation")
+    expect(res.body.error.details).toEqual([{ field: "threshold", message: "Must be a positive integer" }])
+  })
+
+  it("returns 404 NOT_FOUND for unknown routes", async () => {
+    const res = await request(app).get("/nope")
+    expect(res.status).toBe(404)
+    expectEnvelope(res.body)
+    expect(res.body.error.code).toBe("NOT_FOUND")
+    expect(res.body.error.correlationId).toBe(res.headers["x-request-id"])
+  })
+
+  it("returns 400 INVALID_JSON for malformed JSON bodies", async () => {
+    const res = await request(app)
+      .post("/api/treasury/threshold")
+      .set("Content-Type", "application/json")
+      .send("{not json")
+
+    expect(res.status).toBe(400)
+    expectEnvelope(res.body)
+    expect(res.body.error.code).toBe("INVALID_JSON")
+    expect(res.body.error.correlationId).toBe(res.headers["x-request-id"])
+  })
+
+  describe("missing env vars", () => {
+    let backup: string | undefined
+    beforeEach(() => {
+      backup = process.env.SOROBAN_RPC_URL
+      delete process.env.SOROBAN_RPC_URL
+    })
+    afterEach(() => {
+      if (backup !== undefined) process.env.SOROBAN_RPC_URL = backup
+    })
+
+    it("returns 503 SERVICE_MISCONFIGURED", async () => {
+      const res = await request(app).get("/api/treasury/threshold")
+      expect(res.status).toBe(503)
+      expectEnvelope(res.body)
+      expect(res.body.error.code).toBe("SERVICE_MISCONFIGURED")
+      expect(res.body.error.details).toBeNull()
+    })
+  })
+})
+
+describe("toAppError", () => {
+  it("passes typed errors through unchanged", () => {
+    const err = new NotFoundError("gone")
+    expect(toAppError(err)).toBe(err)
+    expect(new ValidationError("bad").status).toBe(400)
+  })
+
+  it("maps legacy status-tagged errors to a code by status", () => {
+    const err = toAppError(Object.assign(new Error("Transaction confirmation timeout"), { status: 504 }))
+    expect(err).toBeInstanceOf(AppError)
+    expect(err.status).toBe(504)
+    expect(err.code).toBe("GATEWAY_TIMEOUT")
+    expect(err.message).toBe("Transaction confirmation timeout")
+  })
+
+  it("extracts the contract code from Soroban host errors", () => {
+    const err = toAppError(
+      Object.assign(new Error("Soroban simulation failed: HostError: Error(Contract, #7) INSUFFICIENT_BALANCE"), {
+        status: 422,
+      }),
+    )
+    expect(err).toBeInstanceOf(ContractError)
+    expect(err.status).toBe(422)
+    expect(err.code).toBe("CONTRACT_ERROR")
+    expect(err.details).toEqual({ contractCode: 7 })
+  })
+
+  it("defaults unknown errors to 500 INTERNAL_ERROR", () => {
+    const err = toAppError("boom")
+    expect(err.status).toBe(500)
+    expect(err.code).toBe("INTERNAL_ERROR")
+  })
+})
diff --git a/comebackhere-backend/src/tests/invoice-settings.test.ts b/comebackhere-backend/src/tests/invoice-settings.test.ts
index 1549f38..522aebd 100644
--- a/comebackhere-backend/src/tests/invoice-settings.test.ts
+++ b/comebackhere-backend/src/tests/invoice-settings.test.ts
@@ -49,7 +49,7 @@ describe("POST /api/invoice/grace-window — boundary validation", () => {
       .send({ grace_window_seconds: -1 })
 
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/positive integer/)
+    expect(res.body.error.message).toMatch(/positive integer/)
   })
 
   it("400 when grace_window_seconds is zero", async () => {
@@ -58,7 +58,7 @@ describe("POST /api/invoice/grace-window — boundary validation", () => {
       .send({ grace_window_seconds: 0 })
 
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/positive integer/)
+    expect(res.body.error.message).toMatch(/positive integer/)
   })
 
   it("400 when grace_window_seconds is a float", async () => {
@@ -67,7 +67,7 @@ describe("POST /api/invoice/grace-window — boundary validation", () => {
       .send({ grace_window_seconds: 1.5 })
 
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/positive integer/)
+    expect(res.body.error.message).toMatch(/positive integer/)
   })
 
   it("400 when grace_window_seconds is a string", async () => {
@@ -76,7 +76,7 @@ describe("POST /api/invoice/grace-window — boundary validation", () => {
       .send({ grace_window_seconds: "86400" })
 
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/positive integer/)
+    expect(res.body.error.message).toMatch(/positive integer/)
   })
 
   it("400 when grace_window_seconds is missing", async () => {
@@ -85,7 +85,7 @@ describe("POST /api/invoice/grace-window — boundary validation", () => {
       .send({})
 
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/positive integer/)
+    expect(res.body.error.message).toMatch(/positive integer/)
   })
 
   // ── Upper-bound validation ───────────────────────────────────────────────────
@@ -96,8 +96,8 @@ describe("POST /api/invoice/grace-window — boundary validation", () => {
       .send({ grace_window_seconds: MAX_GRACE_WINDOW_SECONDS + 1 })
 
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/must not exceed/)
-    expect(res.body.error).toContain(String(MAX_GRACE_WINDOW_SECONDS))
+    expect(res.body.error.message).toMatch(/must not exceed/)
+    expect(res.body.error.message).toContain(String(MAX_GRACE_WINDOW_SECONDS))
   })
 
   it("400 when grace_window_seconds is a very large number (e.g., MAX_SAFE_INTEGER)", async () => {
@@ -106,7 +106,7 @@ describe("POST /api/invoice/grace-window — boundary validation", () => {
       .send({ grace_window_seconds: Number.MAX_SAFE_INTEGER })
 
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/must not exceed/)
+    expect(res.body.error.message).toMatch(/must not exceed/)
   })
 
   // ── Valid boundary values ───────────────────────────────────────────────────
@@ -121,7 +121,7 @@ describe("POST /api/invoice/grace-window — boundary validation", () => {
 
     // Should reach the env-check layer, not a validation layer
     expect(res.status).toBe(503)
-    expect(res.body.error).toMatch(/misconfiguration/)
+    expect(res.body.error.message).toMatch(/misconfiguration/)
   })
 
   it("reaches the Soroban layer (503 env error) with grace_window_seconds = 86400 (1 day)", async () => {
@@ -131,7 +131,7 @@ describe("POST /api/invoice/grace-window — boundary validation", () => {
       .send({ grace_window_seconds: 86_400 })
 
     expect(res.status).toBe(503)
-    expect(res.body.error).toMatch(/misconfiguration/)
+    expect(res.body.error.message).toMatch(/misconfiguration/)
   })
 
   it("reaches the Soroban layer (503 env error) with grace_window_seconds at the 30-day max", async () => {
@@ -141,7 +141,7 @@ describe("POST /api/invoice/grace-window — boundary validation", () => {
       .send({ grace_window_seconds: MAX_GRACE_WINDOW_SECONDS })
 
     expect(res.status).toBe(503)
-    expect(res.body.error).toMatch(/misconfiguration/)
+    expect(res.body.error.message).toMatch(/misconfiguration/)
   })
 
   // ── Error message is consumable by GraceWindowSettings ─────────────────────
@@ -152,8 +152,8 @@ describe("POST /api/invoice/grace-window — boundary validation", () => {
       .send({ grace_window_seconds: -100 })
 
     expect(res.body).toHaveProperty("error")
-    expect(typeof res.body.error).toBe("string")
-    expect(res.body.error.length).toBeGreaterThan(0)
+    expect(typeof res.body.error.message).toBe("string")
+    expect(res.body.error.message.length).toBeGreaterThan(0)
   })
 })
 
diff --git a/comebackhere-backend/src/tests/invoices.test.ts b/comebackhere-backend/src/tests/invoices.test.ts
index c131bdb..9b6cf26 100644
--- a/comebackhere-backend/src/tests/invoices.test.ts
+++ b/comebackhere-backend/src/tests/invoices.test.ts
@@ -79,46 +79,46 @@ describe("POST /invoices — HTTP layer", () => {
       const { merchant_address: _, ...body } = VALID_BODY
       const res = await request(app).post("/invoices").send(body)
       expect(res.status).toBe(400)
-      expect(res.body.error).toMatch(/merchant_address/)
+      expect(res.body.error.message).toMatch(/merchant_address/)
     })
 
     it("400 when merchant_address is not a valid Stellar key", async () => {
       const res = await request(app).post("/invoices").send({ ...VALID_BODY, merchant_address: "NOTAKEY" })
       expect(res.status).toBe(400)
-      expect(res.body.error).toMatch(/merchant_address/)
+      expect(res.body.error.message).toMatch(/merchant_address/)
     })
 
     it("400 when token is missing", async () => {
       const { token: _, ...body } = VALID_BODY
       const res = await request(app).post("/invoices").send(body)
       expect(res.status).toBe(400)
-      expect(res.body.error).toMatch(/token/)
+      expect(res.body.error.message).toMatch(/token/)
     })
 
     it("400 when amount is missing", async () => {
       const { amount: _, ...body } = VALID_BODY
       const res = await request(app).post("/invoices").send(body)
       expect(res.status).toBe(400)
-      expect(res.body.error).toMatch(/amount/)
+      expect(res.body.error.message).toMatch(/amount/)
     })
 
     it("400 when amount is zero or negative", async () => {
       const res = await request(app).post("/invoices").send({ ...VALID_BODY, amount: -1 })
       expect(res.status).toBe(400)
-      expect(res.body.error).toMatch(/amount/)
+      expect(res.body.error.message).toMatch(/amount/)
     })
 
     it("400 when due_date is missing", async () => {
       const { due_date: _, ...body } = VALID_BODY
       const res = await request(app).post("/invoices").send(body)
       expect(res.status).toBe(400)
-      expect(res.body.error).toMatch(/due_date/)
+      expect(res.body.error.message).toMatch(/due_date/)
     })
 
     it("400 when due_date is in the past", async () => {
       const res = await request(app).post("/invoices").send({ ...VALID_BODY, due_date: 1000 })
       expect(res.status).toBe(400)
-      expect(res.body.error).toMatch(/due_date/)
+      expect(res.body.error.message).toMatch(/due_date/)
     })
   })
 
@@ -126,7 +126,7 @@ describe("POST /invoices — HTTP layer", () => {
     delete process.env.SOROBAN_RPC_URL
     const res = await request(app).post("/invoices").send(VALID_BODY)
     expect(res.status).toBe(503)
-    expect(res.body.error).toMatch(/misconfiguration/)
+    expect(res.body.error.message).toMatch(/misconfiguration/)
   })
 })
 
@@ -313,19 +313,19 @@ describe("GET /invoices — pagination", () => {
   it("400 when limit is not a positive integer", async () => {
     const res = await request(app).get("/invoices?limit=abc")
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/limit/)
+    expect(res.body.error.message).toMatch(/limit/)
   })
 
   it("400 when limit is zero", async () => {
     const res = await request(app).get("/invoices?limit=0")
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/limit/)
+    expect(res.body.error.message).toMatch(/limit/)
   })
 
   it("400 when offset is negative", async () => {
     const res = await request(app).get("/invoices?offset=-1")
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/offset/)
+    expect(res.body.error.message).toMatch(/offset/)
   })
 
   it("returns empty data array with correct total when no invoices match", async () => {
@@ -366,6 +366,6 @@ describe("GET /invoices — pagination", () => {
 
     const res = await request(app).get("/invoices")
     expect(res.status).toBe(500)
-    expect(res.body.error).toMatch(/db unavailable/)
+    expect(res.body.error.message).toMatch(/db unavailable/)
   })
 })
\ No newline at end of file
diff --git a/comebackhere-backend/src/tests/mongo-hardening.test.ts b/comebackhere-backend/src/tests/mongo-hardening.test.ts
index 3218e0e..5b9f3b8 100644
--- a/comebackhere-backend/src/tests/mongo-hardening.test.ts
+++ b/comebackhere-backend/src/tests/mongo-hardening.test.ts
@@ -201,6 +201,6 @@ describe("GET /api/treasury/pending-settlements — Mongo outage returns 5xx", (
     // whether the route catches the status property from the thrown error.
     expect(res.status).toBeGreaterThanOrEqual(500)
     expect(res.body).toHaveProperty("error")
-    expect(res.body.error).toMatch(/mongodb/i)
+    expect(res.body.error.message).toMatch(/mongodb/i)
   }, 10_000)
 })
diff --git a/comebackhere-backend/src/tests/openapi.test.ts b/comebackhere-backend/src/tests/openapi.test.ts
index 997a181..b1c12d0 100644
--- a/comebackhere-backend/src/tests/openapi.test.ts
+++ b/comebackhere-backend/src/tests/openapi.test.ts
@@ -54,6 +54,15 @@ describe("GET /api-docs/swagger.json — OpenAPI spec endpoint", () => {
     expect(spec.paths["/disputes"]).toHaveProperty("post")
   })
 
+  it("spec covers the dispute read endpoints", async () => {
+    const res = await request(app).get("/api-docs/swagger.json")
+    const spec = res.body
+    expect(spec.paths["/disputes"]).toHaveProperty("get")
+    expect(spec.paths["/disputes/{id}"]).toHaveProperty("get")
+    expect(spec.paths["/disputes/{id}"].get.responses).toHaveProperty("404")
+    expect(spec.components.schemas).toHaveProperty("Dispute")
+  })
+
   it("spec covers the /api/invoice/grace-window GET and POST endpoints", async () => {
     const res = await request(app).get("/api-docs/swagger.json")
     const spec = res.body
diff --git a/comebackhere-backend/src/tests/rateLimiter.test.ts b/comebackhere-backend/src/tests/rateLimiter.test.ts
index 14561ee..d9aff51 100644
--- a/comebackhere-backend/src/tests/rateLimiter.test.ts
+++ b/comebackhere-backend/src/tests/rateLimiter.test.ts
@@ -66,7 +66,7 @@ describe("Rate limiting — POST /invoices", () => {
     // Third request must be rate-limited
     const res = await request(app).post("/invoices").send(VALID_BODY)
     expect(res.status).toBe(429)
-    expect(res.body.error).toMatch(/too many requests/i)
+    expect(res.body.error.message).toMatch(/too many requests/i)
     expect(res.headers["retry-after"]).toBeDefined()
     expect(Number(res.headers["retry-after"])).toBeGreaterThan(0)
   })
@@ -78,8 +78,9 @@ describe("Rate limiting — POST /invoices", () => {
 
     const res = await request(app).post("/invoices").send(VALID_BODY)
     expect(res.status).toBe(429)
-    expect(typeof res.body.retryAfter).toBe("number")
-    expect(res.body.retryAfter).toBeGreaterThan(0)
+    expect(res.body.error.code).toBe("RATE_LIMITED")
+    expect(typeof res.body.error.details.retryAfter).toBe("number")
+    expect(res.body.error.details.retryAfter).toBeGreaterThan(0)
   })
 
   it("includes X-RateLimit-Limit on normal (non-429) responses", async () => {
diff --git a/comebackhere-backend/src/tests/release-escrow.test.ts b/comebackhere-backend/src/tests/release-escrow.test.ts
index f65c838..83f1e03 100644
--- a/comebackhere-backend/src/tests/release-escrow.test.ts
+++ b/comebackhere-backend/src/tests/release-escrow.test.ts
@@ -79,7 +79,7 @@ describe("POST /invoices/:id/release-escrow — HTTP layer", () => {
   it("401 when x-admin-key header is missing", async () => {
     const res = await request(app).post("/invoices/1/release-escrow").send()
     expect(res.status).toBe(401)
-    expect(res.body.error).toMatch(/Unauthorized/)
+    expect(res.body.error.message).toMatch(/Unauthorized/)
   })
 
   it("401 when x-admin-key header is wrong", async () => {
@@ -88,7 +88,7 @@ describe("POST /invoices/:id/release-escrow — HTTP layer", () => {
       .set("x-admin-key", "wrong-key")
       .send()
     expect(res.status).toBe(401)
-    expect(res.body.error).toMatch(/Unauthorized/)
+    expect(res.body.error.message).toMatch(/Unauthorized/)
   })
 
   it("400 when id is not a positive integer", async () => {
@@ -97,7 +97,7 @@ describe("POST /invoices/:id/release-escrow — HTTP layer", () => {
       .set("x-admin-key", ADMIN_KEY)
       .send()
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/positive integer/)
+    expect(res.body.error.message).toMatch(/positive integer/)
   })
 
   it("400 when id is zero", async () => {
@@ -106,7 +106,7 @@ describe("POST /invoices/:id/release-escrow — HTTP layer", () => {
       .set("x-admin-key", ADMIN_KEY)
       .send()
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/positive integer/)
+    expect(res.body.error.message).toMatch(/positive integer/)
   })
 
   it("503 when required env vars are missing", async () => {
@@ -116,7 +116,7 @@ describe("POST /invoices/:id/release-escrow — HTTP layer", () => {
       .set("x-admin-key", ADMIN_KEY)
       .send()
     expect(res.status).toBe(503)
-    expect(res.body.error).toMatch(/misconfiguration/)
+    expect(res.body.error.message).toMatch(/misconfiguration/)
   })
 })
 
@@ -179,7 +179,7 @@ describe("POST /invoices/:id/release-escrow — authorization", () => {
       .send()
 
     expect(res.status).toBe(401)
-    expect(res.body.error).toMatch(/Unauthorized/)
+    expect(res.body.error.message).toMatch(/Unauthorized/)
   })
 
   it("401 — unauthorized caller with wrong x-admin-key is rejected (unauthorized-caller-rejection)", async () => {
@@ -190,7 +190,7 @@ describe("POST /invoices/:id/release-escrow — authorization", () => {
       .send()
 
     expect(res.status).toBe(401)
-    expect(res.body.error).toMatch(/Unauthorized/)
+    expect(res.body.error.message).toMatch(/Unauthorized/)
   })
 
   it("403 — on-chain Unauthorized contract error maps to 403 Forbidden", async () => {
@@ -213,8 +213,9 @@ describe("POST /invoices/:id/release-escrow — authorization", () => {
       .send()
 
     expect(res.status).toBe(403)
-    expect(res.body.error).toMatch(/authoris/)
-    expect(res.body.code).toBe(1)
+    expect(res.body.error.message).toMatch(/authoris/)
+    expect(res.body.error.code).toBe("CONTRACT_ERROR")
+    expect(res.body.error.details).toEqual({ contractCode: 1 })
   })
 })
 
diff --git a/comebackhere-backend/src/tests/security-headers.test.ts b/comebackhere-backend/src/tests/security-headers.test.ts
new file mode 100644
index 0000000..cb4bb31
--- /dev/null
+++ b/comebackhere-backend/src/tests/security-headers.test.ts
@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest"
+import request from "supertest"
+import { createApp } from "../app.js"
+
+describe("security headers", () => {
+  const app = createApp()
+
+  it("sets the helmet baseline on API responses", async () => {
+    const res = await request(app).get("/health")
+
+    expect(res.status).toBe(200)
+    expect(res.headers["x-content-type-options"]).toBe("nosniff")
+    expect(res.headers["strict-transport-security"]).toMatch(/max-age=\d+/)
+    expect(res.headers["x-frame-options"]).toBe("SAMEORIGIN")
+    expect(res.headers["referrer-policy"]).toBe("no-referrer")
+    expect(res.headers["x-powered-by"]).toBeUndefined()
+  })
+
+  it("uses a strict Content-Security-Policy for the JSON API", async () => {
+    const res = await request(app).get("/health")
+    const csp = res.headers["content-security-policy"]
+
+    expect(csp).toContain("default-src 'none'")
+    expect(csp).toContain("frame-ancestors 'none'")
+  })
+
+  it("sets security headers on error responses too", async () => {
+    const res = await request(app).get("/does-not-exist")
+
+    expect(res.status).toBe(404)
+    expect(res.headers["x-content-type-options"]).toBe("nosniff")
+    expect(res.headers["content-security-policy"]).toContain("default-src 'none'")
+  })
+
+  it("still lets Swagger UI load its same-origin assets", async () => {
+    const page = await request(app).get("/api-docs/")
+    expect(page.status).toBe(200)
+    expect(page.text).toContain("swagger-ui-bundle.js")
+
+    const csp = page.headers["content-security-policy"]
+    expect(csp).toContain("script-src 'self'")
+    expect(csp).toContain("style-src 'self' 'unsafe-inline'")
+    expect(csp).toContain("img-src 'self' data:")
+    expect(csp).not.toContain("default-src 'none'")
+
+    for (const asset of ["swagger-ui-bundle.js", "swagger-ui-init.js", "swagger-ui.css"]) {
+      const res = await request(app).get(`/api-docs/${asset}`)
+      expect(res.status, asset).toBe(200)
+    }
+  })
+})
+
+describe("JSON body size limit", () => {
+  const app = createApp()
+
+  it("returns 413 in the standard envelope for bodies over 100kb", async () => {
+    const res = await request(app)
+      .post("/api/treasury/threshold")
+      .set("Content-Type", "application/json")
+      .set("X-Request-Id", "req-too-large")
+      .send(JSON.stringify({ threshold: 1, padding: "x".repeat(101 * 1024) }))
+
+    expect(res.status).toBe(413)
+    expect(res.headers["content-type"]).toMatch(/application\/json/)
+    expect(res.body).toEqual({
+      error: {
+        code: "PAYLOAD_TOO_LARGE",
+        message: "Request body exceeds the maximum allowed size",
+        details: { limitBytes: 100 * 1024 },
+        correlationId: "req-too-large",
+      },
+    })
+  })
+
+  it("accepts bodies under the limit", async () => {
+    const res = await request(app)
+      .post("/api/treasury/threshold")
+      .set("Content-Type", "application/json")
+      .send(JSON.stringify({ threshold: -1, padding: "x".repeat(50 * 1024) }))
+
+    // Reaches validation (400) rather than being rejected for size
+    expect(res.status).toBe(400)
+    expect(res.body.error.code).toBe("VALIDATION_ERROR")
+  })
+})
diff --git a/comebackhere-backend/src/tests/treasury.test.ts b/comebackhere-backend/src/tests/treasury.test.ts
index a72e175..cfae6f8 100644
--- a/comebackhere-backend/src/tests/treasury.test.ts
+++ b/comebackhere-backend/src/tests/treasury.test.ts
@@ -72,7 +72,7 @@ describe("POST /api/treasury/execute-settlement", () => {
   it("400 when settlement_id is missing", async () => {
     const res = await request(app).post("/api/treasury/execute-settlement").send({})
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/settlement_id/)
+    expect(res.body.error.message).toMatch(/settlement_id/)
   })
 
   it("503 when required env vars are missing", async () => {
@@ -173,7 +173,7 @@ describe("invoice grace window routes", () => {
       .post("/api/invoice/grace-window")
       .send({ grace_window_seconds: -1 })
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/grace_window_seconds/)
+    expect(res.body.error.message).toMatch(/grace_window_seconds/)
   })
 })
 
@@ -442,7 +442,7 @@ describe("POST /api/treasury/simulate-settlement", () => {
   it("400 when settlement_id is missing", async () => {
     const res = await request(app).post("/api/treasury/simulate-settlement").send({})
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/settlement_id/)
+    expect(res.body.error.message).toMatch(/settlement_id/)
   })
 
   it("503 when required env vars are missing", async () => {
@@ -481,7 +481,7 @@ describe("POST /api/treasury/execute-settlement — HTTP layer additional cases"
       .post("/api/treasury/execute-settlement")
       .send({ settlement_id: 1.5 })
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/settlement_id/)
+    expect(res.body.error.message).toMatch(/settlement_id/)
   })
 
   it("400 when settlement_id is zero", async () => {
@@ -489,7 +489,7 @@ describe("POST /api/treasury/execute-settlement — HTTP layer additional cases"
       .post("/api/treasury/execute-settlement")
       .send({ settlement_id: 0 })
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/settlement_id/)
+    expect(res.body.error.message).toMatch(/settlement_id/)
   })
 })
 
@@ -571,7 +571,7 @@ describe("GET /api/treasury/on-hold-settlements", () => {
 
     const res = await request(app).get("/api/treasury/on-hold-settlements")
     expect(res.status).toBe(500)
-    expect(res.body.error).toMatch(/mongo down/)
+    expect(res.body.error.message).toMatch(/mongo down/)
   })
 })
 
@@ -598,7 +598,7 @@ describe("POST /api/treasury/release-hold", () => {
   it("400 when settlement_id is missing", async () => {
     const res = await request(app).post("/api/treasury/release-hold").send({})
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/settlement_id/)
+    expect(res.body.error.message).toMatch(/settlement_id/)
   })
 
   it("400 when settlement_id is zero", async () => {
@@ -606,7 +606,7 @@ describe("POST /api/treasury/release-hold", () => {
       .post("/api/treasury/release-hold")
       .send({ settlement_id: 0 })
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/settlement_id/)
+    expect(res.body.error.message).toMatch(/settlement_id/)
   })
 
   it("404 when settlement is not found or not on hold", async () => {
@@ -621,7 +621,7 @@ describe("POST /api/treasury/release-hold", () => {
       .post("/api/treasury/release-hold")
       .send({ settlement_id: 999 })
     expect(res.status).toBe(404)
-    expect(res.body.error).toMatch(/not found or not on hold/i)
+    expect(res.body.error.message).toMatch(/not found or not on hold/i)
   })
 
   it("200 and returns updated record when successfully released", async () => {
@@ -686,7 +686,7 @@ describe("POST /api/treasury/release-hold", () => {
       .post("/api/treasury/release-hold")
       .send({ settlement_id: 1 })
     expect(res.status).toBe(500)
-    expect(res.body.error).toMatch(/db failure/)
+    expect(res.body.error.message).toMatch(/db failure/)
   })
 })
 
@@ -713,7 +713,7 @@ describe("POST /api/treasury/escalate-hold", () => {
   it("400 when settlement_id is missing", async () => {
     const res = await request(app).post("/api/treasury/escalate-hold").send({})
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/settlement_id/)
+    expect(res.body.error.message).toMatch(/settlement_id/)
   })
 
   it("400 when settlement_id is not a positive integer", async () => {
@@ -721,7 +721,7 @@ describe("POST /api/treasury/escalate-hold", () => {
       .post("/api/treasury/escalate-hold")
       .send({ settlement_id: -1 })
     expect(res.status).toBe(400)
-    expect(res.body.error).toMatch(/settlement_id/)
+    expect(res.body.error.message).toMatch(/settlement_id/)
   })
 
   it("404 when settlement is not found or not on hold", async () => {
@@ -736,7 +736,7 @@ describe("POST /api/treasury/escalate-hold", () => {
       .post("/api/treasury/escalate-hold")
       .send({ settlement_id: 999 })
     expect(res.status).toBe(404)
-    expect(res.body.error).toMatch(/not found or not on hold/i)
+    expect(res.body.error.message).toMatch(/not found or not on hold/i)
   })
 
   it("200 and returns escalated record with hold_reason: AdminHold", async () => {
@@ -806,7 +806,7 @@ describe("POST /api/treasury/escalate-hold", () => {
       .post("/api/treasury/escalate-hold")
       .send({ settlement_id: 70 })
     expect(res.status).toBe(404)
-    expect(res.body.error).toMatch(/not found or not on hold/i)
+    expect(res.body.error.message).toMatch(/not found or not on hold/i)
   })
 
   it("500 on database error", async () => {
@@ -816,6 +816,6 @@ describe("POST /api/treasury/escalate-hold", () => {
       .post("/api/treasury/escalate-hold")
       .send({ settlement_id: 1 })
     expect(res.status).toBe(500)
-    expect(res.body.error).toMatch(/connection lost/)
+    expect(res.body.error.message).toMatch(/connection lost/)
   })
 })
\ No newline at end of file
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 0eab435..08f3468 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -2,9 +2,25 @@
 
 Base URL: `http://localhost:3000` (local) or your deployed backend.
 
-All request bodies are JSON (`Content-Type: application/json`).
+All request bodies are JSON (`Content-Type: application/json`) and are limited
+to **100 kB**; larger bodies are rejected with `413 PAYLOAD_TOO_LARGE`.
 All responses are JSON.
 
+**CORS:** browsers may call the API only from origins listed in
+`CORS_ORIGINS`. Requests from any other origin, including preflights, get
+`403 CORS_ORIGIN_NOT_ALLOWED`. Preflight allows the `Content-Type`,
+`Authorization`, `Idempotency-Key`, `X-Request-Id` and `X-Admin-Key` request
+headers, and exposes `X-Request-Id`, `Retry-After` and the `X-RateLimit-*`
+response headers. Requests with no `Origin` header (server-to-server, curl)
+are unaffected.
+
+Every response carries a baseline of security headers (via
+[helmet](https://helmetjs.github.io/)), including `Strict-Transport-Security`,
+`X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer` and a strict
+`Content-Security-Policy: default-src 'none'`. Swagger UI under `/api-docs`
+gets a relaxed CSP that allows its same-origin scripts, inline styles and
+`data:` images.
+
 > **Machine-readable spec:** A Swagger/OpenAPI 3.0 spec is served at
 > [`GET /api-docs/swagger.json`](http://localhost:3000/api-docs/swagger.json) (raw JSON)
 > and [`GET /api-docs`](http://localhost:3000/api-docs) (interactive Swagger UI).
@@ -12,6 +28,10 @@ All responses are JSON.
 > **Rate limits:** All endpoints are subject to per-IP rate limiting. See
 > [docs/rate-limits.md](./rate-limits.md) for default limits, configuration,
 > and the 429 response shape.
+>
+> **Errors:** Every error uses one envelope,
+> `{ "error": { "code", "message", "details", "correlationId" } }`. See
+> [Error response shape](#error-response-shape).
 
 ---
 
@@ -120,7 +140,7 @@ Create a new invoice by submitting `create_invoice` to the Soroban RPC.
 
 | Status | Description                                                    |
 | ------ | -------------------------------------------------------------- |
-| `400`  | Validation error — see `error` field for detail                |
+| `400`  | Validation error — see `error.details` for field-level detail  |
 | `422`  | Soroban simulation or transaction failure                      |
 | `503`  | Missing required environment variables                         |
 | `504`  | Transaction confirmation timeout                               |
@@ -208,10 +228,114 @@ Raise a dispute linked to a settlement, transitioning it to `OnHold`.
 
 | Status | Description                                                    |
 | ------ | -------------------------------------------------------------- |
-| `400`  | Validation error — see `error` field for detail                |
+| `400`  | Validation error — see `error.details` for field-level detail  |
 | `503`  | Missing required environment variables                         |
 | `500`  | Unexpected server error                                        |
 
+### `GET /disputes`
+
+List disputes with their current vote tallies, newest first.
+
+#### Query parameters
+
+| Parameter       | Type    | Default | Description                                   |
+| --------------- | ------- | ------- | --------------------------------------------- |
+| `status`        | string  | —       | `Raised` (open) or `Resolved`                 |
+| `settlement_id` | string  | —       | Only disputes for this settlement             |
+| `page`          | integer | `1`     | 1-based page number                           |
+| `limit`         | integer | `20`    | Page size, 1–100                              |
+
+Send `x-admin-key` to include voter identities (see
+[Voter visibility](#voter-visibility)).
+
+**Response `200`**
+
+```json
+{
+  "data": [
+    {
+      "dispute_id": "5-1720000000000",
+      "settlement_id": "5",
+      "claimant_address": "G...",
+      "reason": "Goods not delivered",
+      "status": "Raised",
+      "outcome": null,
+      "claimant_weight": 1,
+      "counterparty_weight": 0,
+      "resolution_weight": 1,
+      "threshold": 2,
+      "vote_count": 1,
+      "created_at": "2026-09-25T10:00:00.000Z",
+      "resolved_at": null
+    }
+  ],
+  "total": 1,
+  "page": 1,
+  "limit": 20,
+  "totalPages": 1
+}
+```
+
+#### Errors
+
+| Status | Description                                                   |
+| ------ | ------------------------------------------------------------- |
+| `400`  | Invalid query parameter — see `error.details`                 |
+| `401`  | `x-admin-key` supplied but invalid                            |
+
+### `GET /disputes/:id`
+
+Full details for one dispute: the same fields as a list item. For admins it
+also includes `votes`:
+
+```json
+{
+  "dispute_id": "5-1720000000000",
+  "status": "Resolved",
+  "outcome": "ResolvedClaimant",
+  "claimant_weight": 2,
+  "counterparty_weight": 1,
+  "resolution_weight": 3,
+  "threshold": 2,
+  "vote_count": 3,
+  "resolved_at": "2026-09-25T10:05:00.000Z",
+  "votes": [
+    { "signer": "G...", "vote": "ResolvedClaimant", "weight": 1, "voted_at": "2026-09-25T10:01:00.000Z" }
+  ]
+}
+```
+
+#### Errors
+
+| Status | Description                                   |
+| ------ | --------------------------------------------- |
+| `401`  | `x-admin-key` supplied but invalid            |
+| `404`  | No dispute with this ID                       |
+
+### `POST /disputes/:id/vote`
+
+Cast a weighted vote (`ResolvedClaimant` or `ResolvedCounterparty`). The
+dispute resolves as soon as either side's weight reaches the threshold
+(`DISPUTE_VOTE_THRESHOLD`, default `2`).
+
+| Status | Description                                                            |
+| ------ | ---------------------------------------------------------------------- |
+| `400`  | Validation error                                                       |
+| `404`  | No dispute with this ID                                                |
+| `409`  | Signer already voted, or dispute already resolved (`details.outcome`)  |
+
+### Voter visibility
+
+Tallies (`claimant_weight`, `counterparty_weight`, `resolution_weight`,
+`vote_count`, `outcome`) are public. **Who voted which way is visible only to
+admins** (a valid `x-admin-key` header), via the `votes` array.
+
+Signers are the treasury's multi-sig keys. Publishing each key's vote in a
+public API makes it easy to single out and pressure individual signers, and
+clients showing dispute progress only need the tallies. The API hides voter
+identities as a precaution: on-chain votes are still public on the ledger,
+so this is not a confidentiality guarantee.
+
 ---
 
 ## Treasury
@@ -745,12 +869,57 @@ webhook delivery is skipped silently (no error).
 
 ## Error response shape
 
-All error responses share this shape:
+Every non-2xx response, from every endpoint, uses the same envelope:
 
 ```json
-{ "error": "Human-readable description of the error." }
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "settlement_id: Must be a positive integer",
+    "details": [{ "field": "settlement_id", "message": "Must be a positive integer" }],
+    "correlationId": "5f1c9a8e-2b7d-4c1e-9a3f-0d2e6b7c8a91"
+  }
+}
 ```
 
+| Field           | Type           | Description                                                                                   |
+| --------------- | -------------- | --------------------------------------------------------------------------------------------- |
+| `code`          | string         | Stable, machine-readable error code (see below). Branch on this, not on `message`.            |
+| `message`       | string         | Human-readable description. May change between releases.                                      |
+| `details`       | any \| null    | Extra structured context; shape depends on `code`. `null` when there is nothing to add.        |
+| `correlationId` | string \| null | Same value as the `X-Request-Id` response header. Quote it when contacting support.           |
+
+Clients may send their own `X-Request-Id` header; it is echoed back as both the
+header and `correlationId`. Otherwise the server generates a UUID v4.
+
+### Error codes
+
+| HTTP | `code`                  | When                                                             | `details`                              |
+| ---- | ----------------------- | ---------------------------------------------------------------- | -------------------------------------- |
+| 400  | `VALIDATION_ERROR`      | Body, path or query parameters failed schema validation          | `[{ field, message }]`, one per issue  |
+| 400  | `INVALID_JSON`          | Request body is not valid JSON                                   | `null`                                 |
+| 401  | `UNAUTHORIZED`          | Missing or invalid `x-admin-key`                                 | `null`                                 |
+| 403  | `FORBIDDEN`             | Caller lacks permission                                          | `null`                                 |
+| 403  | `CORS_ORIGIN_NOT_ALLOWED` | Browser `Origin` is not in `CORS_ORIGINS`                      | `{ origin }`                           |
+| 404  | `NOT_FOUND`             | Resource or route does not exist                                 | `null`                                 |
+| 409  | `CONFLICT`              | Request conflicts with current state (e.g. dispute already resolved) | Endpoint-specific, e.g. `{ outcome }` |
+| 413  | `PAYLOAD_TOO_LARGE`     | JSON body exceeds 100 kB                                         | `{ limitBytes }`                       |
+| 4xx/5xx | `CONTRACT_ERROR`     | A Soroban contract returned `Error(Contract, #N)`                | `{ contractCode: N }` — see [error-codes.md](./error-codes.md) |
+| 422  | `UNPROCESSABLE_ENTITY`  | Soroban simulation / submission failed without a contract code   | `null`                                 |
+| 429  | `RATE_LIMITED`          | Per-IP rate limit exceeded                                       | `{ retryAfter }` (seconds)             |
+| 500  | `INTERNAL_ERROR`        | Unexpected server error                                          | `null`                                 |
+| 503  | `SERVICE_MISCONFIGURED` | Required environment variables are missing                       | `null`                                 |
+| 503  | `SERVICE_UNAVAILABLE`   | A dependency (e.g. MongoDB) is unreachable                       | `null`                                 |
+| 504  | `GATEWAY_TIMEOUT`       | Timed out waiting for Soroban transaction confirmation           | `null`                                 |
+
+### Server implementation
+
+Routes do not build error responses by hand. They throw a typed error from
+`comebackhere-backend/src/lib/errors.ts` (`ValidationError`, `NotFoundError`,
+`ConflictError`, `UnauthorizedError`, `ContractError`, …) and the central
+handler in `src/middleware/errorHandler.ts` renders the envelope. Async
+handlers are wrapped in `asyncHandler` so rejected promises reach it.
+
 ## Environment variables
 
 | Variable               | Description                                               |
@@ -765,3 +934,4 @@ All error responses share this shape:
 | `WEBHOOK_URL`          | Merchant webhook endpoint URL                             |
 | `WEBHOOK_SIGNING_SECRET` | HMAC-SHA256 signing secret for outbound webhooks        |
 | `PORT`                 | HTTP server port (default `3000`)                         |
+| `CORS_ORIGINS`         | Comma-separated allowlist of browser origins, e.g. `http://localhost:5173,https://app.example.com`. Bare origins only (no path, trailing slash or `*`); invalid entries fail startup. Unset = no cross-origin access. |
diff --git a/docs/error-codes.md b/docs/error-codes.md
index 6e1e4df..0f707aa 100644
--- a/docs/error-codes.md
+++ b/docs/error-codes.md
@@ -126,16 +126,23 @@ Defined in `COMEBACKHERE-contracts/contracts/treasury/src/lib.rs`.
 
 ## Error shape in API responses
 
-Backend endpoints return errors as JSON:
+Backend endpoints return errors in the standard envelope (see
+[api-reference.md § Error response shape](./api-reference.md#error-response-shape)).
+When a contract rejects a call, `code` is `CONTRACT_ERROR` and
+`details.contractCode` holds the numeric value from the tables above:
 
 ```json
 {
-  "error": "Human-readable message",
-  "code": 6
+  "error": {
+    "code": "CONTRACT_ERROR",
+    "message": "Soroban simulation failed: HostError: Error(Contract, #6) ...",
+    "details": { "contractCode": 6 },
+    "correlationId": "5f1c9a8e-2b7d-4c1e-9a3f-0d2e6b7c8a91"
+  }
 }
 ```
 
-`code` corresponds directly to the numeric values in the tables above. When `code` is `null` or absent the error originates from the RPC layer rather than the contract.
+Any other `code` means the error originates from validation, configuration, or the RPC layer rather than the contract.
 
 ---
 
diff --git a/docs/rate-limits.md b/docs/rate-limits.md
index fc76185..167c819 100644
--- a/docs/rate-limits.md
+++ b/docs/rate-limits.md
@@ -74,15 +74,21 @@ shape:
 
 ```json
 {
-  "error": "Too many requests. Please retry after the indicated number of seconds.",
-  "retryAfter": 12
+  "error": {
+    "code": "RATE_LIMITED",
+    "message": "Too many requests. Please retry after the indicated number of seconds.",
+    "details": { "retryAfter": 12 },
+    "correlationId": "5f1c9a8e-2b7d-4c1e-9a3f-0d2e6b7c8a91"
+  }
 }
 ```
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `error` | string | Human-readable message. |
-| `retryAfter` | number | Seconds to wait before retrying. |
+| `error.code` | string | Always `RATE_LIMITED`. |
+| `error.message` | string | Human-readable message. |
+| `error.details.retryAfter` | number | Seconds to wait before retrying. |
+| `error.correlationId` | string | Same as the `X-Request-Id` response header. |
 
 The response also includes a `Retry-After` header with the same integer value,
 plus `X-RateLimit-Limit`, `X-RateLimit-Remaining: 0`, and `X-RateLimit-Reset`.
diff --git a/frontend/src/components/GraceWindowSettings/GraceWindowSettings.tsx b/frontend/src/components/GraceWindowSettings/GraceWindowSettings.tsx
index 1689129..53cf5a7 100644
--- a/frontend/src/components/GraceWindowSettings/GraceWindowSettings.tsx
+++ b/frontend/src/components/GraceWindowSettings/GraceWindowSettings.tsx
@@ -81,7 +81,7 @@ export default function GraceWindowSettings() {
       const res = await fetch(`${API_BASE}/invoice/grace-window`)
       if (!res.ok) {
         const body = await res.json().catch(() => ({}))
-        throw new Error(body.error ?? `HTTP ${res.status}`)
+        throw new Error(body.error?.message ?? `HTTP ${res.status}`)
       }
       const data: { grace_window_seconds: number } = await res.json()
       setCurrentSeconds(data.grace_window_seconds)
@@ -135,7 +135,7 @@ export default function GraceWindowSettings() {
       })
       const body = await res.json().catch(() => ({}))
       if (!res.ok) {
-        throw new Error(body.error ?? `HTTP ${res.status}`)
+        throw new Error(body.error?.message ?? `HTTP ${res.status}`)
       }
       setCurrentSeconds(body.grace_window_seconds)
       setSuccess(
diff --git a/frontend/src/components/TreasuryManagerPage/TreasuryManagerPage.tsx b/frontend/src/components/TreasuryManagerPage/TreasuryManagerPage.tsx
index 3fa37a8..b9023cb 100644
--- a/frontend/src/components/TreasuryManagerPage/TreasuryManagerPage.tsx
+++ b/frontend/src/components/TreasuryManagerPage/TreasuryManagerPage.tsx
@@ -33,7 +33,7 @@ async function postTreasuryAction(
     body: JSON.stringify(body),
   })
   const data = await res.json()
-  if (!res.ok) return { success: false, error: data.error ?? `HTTP ${res.status}` }
+  if (!res.ok) return { success: false, error: data.error?.message ?? `HTTP ${res.status}` }
   return { success: true, hash: data.tx_hash }
 }