@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/best-practices/error-handling.md

@@ -1,52 +1,106 @@
 # Error Handling
 
-Comprehensive guide to handling errors gracefully in IGNIS applications.
+Every error in IGNIS ends up as one shape: `statusCode`, `message`, `normalized`, `requestId`, and `details`. `getError` builds that shape at the throw site. A global handler catches whatever you don't.
 
-## Error Handling Philosophy
+```typescript
+import { getError, HTTP } from '@venizia/ignis-helpers';
+
+throw getError({
+  statusCode: HTTP.ResultCodes.RS_4.NotFound,
+  message: 'User not found',
+});
+```
 
-| Principle | Description |
-|-----------|-------------|
-| **Fail Fast** | Detect and report errors as early as possible |
-| **Don't Swallow** | Never catch errors without logging or re-throwing |
-| **User-Friendly** | Return clear, actionable messages to clients |
-| **Debuggable** | Include context for debugging in logs |
+## Find what you need
 
-## 1. Using `getError` Helper
+| You want to | Go to |
+|---|---|
+| Throw an error with debugging context | [Throw a structured error](#throw-a-structured-error) |
+| Add an i18n error a client can branch on | [Catalog a domain error](#catalog-a-domain-error) |
+| Pick the right HTTP status code | [Choose the right status code](#choose-the-right-status-code) |
+| Handle errors in a service, controller, or repository | [Handle errors by layer](#handle-errors-by-layer) |
+| Customize the global error response | [Customize the global handler](#customize-the-global-handler) |
+| Read the exact JSON a client receives | [The error response shape](#the-error-response-shape) |
+| Log an error without losing the stack | [Log errors](#log-errors) |
+| Handle a rejected promise or a fire-and-forget call | [Handle async errors](#handle-async-errors) |
+| Roll back a transaction safely | [Roll back a transaction on failure](#roll-back-a-transaction-on-failure) |
+| Parse an error response on the client | [Parse errors on the client](#parse-errors-on-the-client) |
 
-IGNIS provides `getError` for creating consistent, structured errors.
+## Throw a structured error
+
+`getError` is the one function every throw in IGNIS goes through. Give it a status code and a message, and it returns an `ApplicationError` ready to throw.
 
 ```typescript
 import { getError, HTTP } from '@venizia/ignis-helpers';
 
-// Basic error
+// Error with context - any key the framework does not model lands in `extra`
 throw getError({
-  statusCode: HTTP.ResultCodes.RS_4.NotFound,
-  message: 'User not found',
+  statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+  message: 'Invalid request',
+  details: { field: 'email', reason: 'Must be a valid email address' },
 });
+// -> error.extra.details
 
-// Error with details
+// The same thing, explicit. Prefer this when the context could be mistaken for a field.
 throw getError({
   statusCode: HTTP.ResultCodes.RS_4.BadRequest,
   message: 'Invalid request',
-  details: {
-    field: 'email',
-    reason: 'Must be a valid email address',
-  },
+  extra: { details: { field: 'email' } },
 });
 
-// Error with context (for logging)
+// Wrapping a lower-level failure - `cause` reaches the native Error.cause
 throw getError({
   statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
   message: '[UserService][create] Database connection failed',
-  details: { userId: requestedId },
+  cause: error,
+  extra: { userId: requestedId },
 });
 ```
 
-## 2. HTTP Status Code Reference
+Any key `getError` does not model rides into `extra`. That's how a throw site attaches context the framework knows nothing about.
 
-Use the correct status code for each error type:
+> [!NOTE]
+> The trade-off: a **misspelling** rides the same path. `getError({ message, statuscode: 503 })` compiles. `statusCode` stays `400`, and `503` sits in `extra.statuscode`. The framework can't tell your context from your typo - spell option keys carefully.
 
-| Code | Constant | Use When |
+## Catalog a domain error
+
+A free-form `getError` call like that is right for a failure with no i18n code: an invariant, a misconfiguration, a seed guard. Nobody translates `'[UserService][create] Database connection failed'`.
+
+But a **domain** failure - one a client localizes and branches on - belongs in a catalog instead. Retyping its code and status at each throw is how two call sites end up raising `category.create.duplicate_name` and `category.duplicate_name` for the same thing.
+
+```typescript
+import { ErrorScopes, getError, HTTP } from '@venizia/ignis-helpers';
+import type { TErrorDefinition, TRegisterErrors } from '@venizia/ignis-helpers';
+
+export const UserErrors = {
+  CREATE_DUPLICATE_EMAIL: {
+    message: {
+      text: 'An account with %{email} already exists.',
+      code: 'server.core.user.create.duplicate_email',
+    },
+    statusCode: HTTP.ResultCodes.RS_4.Conflict,
+    category: ErrorScopes.VALIDATION,
+    description: 'Sign-up rejected because the email is already registered.',
+  },
+} as const satisfies Record<string, TErrorDefinition>;
+
+declare module '@venizia/ignis-helpers' {
+  interface IErrorKeyRegistry extends TRegisterErrors<typeof UserErrors> {}
+}
+
+// At every throw site:
+throw getError({ error: UserErrors.CREATE_DUPLICATE_EMAIL, messageArgs: { email } });
+```
+
+Pass the definition as `error` - never spread it. `getError({ ...UserErrors.CREATE_DUPLICATE_EMAIL, messageArgs: { email } })` looks equivalent. It isn't.
+
+Spreading skips the `error:` field entirely. `category` and `description` are fields only a definition models, so they fall into `extra` instead of staying structured. `statusCode` and `message` still resolve correctly, but only because their shapes happen to match what `getError` expects standalone - nothing catches the rest for you.
+
+See the [Error helper reference](/extensions/helpers/error/) for the full surface.
+
+## Choose the right status code
+
+| Code | Constant | Use when |
 |------|----------|----------|
 | 400 | `RS_4.BadRequest` | Invalid input format, missing required fields, database constraint violations (auto-handled) |
 | 401 | `RS_4.Unauthorized` | Missing or invalid authentication |
@@ -59,13 +113,15 @@ Use the correct status code for each error type:
 | 502 | `RS_5.BadGateway` | External service failed |
 | 503 | `RS_5.ServiceUnavailable` | Service temporarily down |
 
-:::tip Automatic Database Error Handling
-Database errors in SQLSTATE classes `22` (data exception), `23` (integrity constraint - unique, foreign key, not null, check, exclusion), and `44` (WITH CHECK OPTION violation) are automatically converted to HTTP 400 by the global error middleware. Transient conflicts (`40001` serialization failure, `40P01` deadlock) become HTTP 409 with a retryable message. You don't need to catch these manually. Other classes (e.g. syntax / undefined column) stay 500, and production responses are sanitized - see [Repository Layer Errors](#repository-layer-errors).
+:::tip Automatic database error handling
+The global error middleware converts constraint violations to HTTP 400 on its own, no try/catch needed - SQLSTATE class `22` (data exception), `23` (integrity constraint: unique, foreign key, not null, check, exclusion), and `44` (WITH CHECK OPTION violation). Transient conflicts (`40001` serialization failure, `40P01` deadlock) become HTTP 409 with a retryable message instead. Other classes (for example, class `42` undefined column) stay 500, and production responses are sanitized - see [Repository layer](#repository-layer).
 :::
 
-## 3. Error Handling Patterns
+## Handle errors by layer
+
+### Service layer
 
-### Service Layer Errors
+A service decides what's wrong and throws with `getError`. It doesn't catch what it can't handle.
 
 ```typescript
 import { BaseService } from '@venizia/ignis';
@@ -90,9 +146,9 @@ export class UserService extends BaseService {
     try {
       await this.emailService.sendWelcome(data.email);
     } catch (error) {
-      // Log but don't fail user creation
+      // Log but don't fail user creation - never a silent catch
       this.logger.error('[createUser] Failed to send welcome email | email: %s | error: %s',
-        data.email, error.message);
+        data.email, error);
     }
 
     // create returns { count, data }
@@ -117,9 +173,11 @@ export class UserService extends BaseService {
 }
 ```
 
-### Controller Layer Errors
+Notice `findOne` and `findById` return the record or `null` - there's no separate "not found" exception to catch. You check for `null` and throw.
 
-Controllers should delegate to services and let the global error handler catch exceptions:
+### Controller layer
+
+Controllers stay thin. Call the service, return the response, and let the global handler catch what the service throws.
 
 ```typescript
 import { BaseRestController, controller, get, post } from '@venizia/ignis';
@@ -149,37 +207,52 @@ export class UserController extends BaseRestController {
 }
 ```
 
-### Repository Layer Errors
+### Repository layer
 
-Database errors in SQLSTATE classes `22` (data exception), `23` (integrity constraint - unique, foreign key, not null, check, exclusion), and `44` (WITH CHECK OPTION violation) are **automatically handled** by the global error middleware and return HTTP 400. Transient conflicts (`40001` serialization failure, `40P01` deadlock) return HTTP 409 with a generic retryable message. Codes outside those classes (e.g. class `42` undefined column - an application/SQL bug) correctly stay 500.
+The global middleware already converts constraint violations for you (see [Choose the right status code](#choose-the-right-status-code)), so most repository methods need no try/catch at all. Skip it unless you want a message tailored to one specific constraint.
 
 **Non-production** returns the full driver context for debugging:
 
 ```json
 {
   "message": "Unique constraint violation\nDetail: Key (email)=(test@example.com) already exists.\nTable: User\nConstraint: UQ_User_email",
-  "messageCode": "core.system_error",
   "statusCode": 400,
-  "requestId": "abc123"
+  "normalized": {
+    "text": "Unique constraint violation\nDetail: Key (email)=(test@example.com) already exists.\nTable: User\nConstraint: UQ_User_email",
+    "code": "core.system_error",
+    "args": {}
+  },
+  "requestId": "abc123",
+  "details": {
+    "url": "http://localhost:3000/users",
+    "path": "/users",
+    "stack": "Error: Unique constraint violation\n    at ..."
+  }
 }
 ```
 
 :::warning Production sanitizes database internals
-In production the message is the **base message only** - `Detail:` (which echoes row values like emails), `Table:`, and `Constraint:` are stripped, and `details.stack`/`details.cause` are omitted. Unexpected (non-client) database errors and connection failures return a generic `"Internal Server Error"`, so SQL, schema names, and connection host/port never leak. Use `requestId` + server logs to diagnose.
+In production the message is the **base message only**. `Detail:` (which echoes row values like emails), `Table:`, and `Constraint:` are stripped, and `details.stack`/`details.cause` are omitted. Unexpected (non-client) database errors and connection failures return a generic `"Internal Server Error"`, so SQL, schema names, and connection host/port never leak. Use `requestId` and server logs to diagnose.
 
 ```json
-{ "message": "Unique constraint violation", "messageCode": "core.system_error", "statusCode": 400, "requestId": "abc123" }
+{
+  "message": "Unique constraint violation",
+  "statusCode": 400,
+  "normalized": { "text": "Unique constraint violation", "code": "core.system_error", "args": {} },
+  "requestId": "abc123",
+  "details": { "url": "http://localhost:3000/users", "path": "/users" }
+}
 ```
 :::
 
-You don't need to wrap repository calls in try-catch for constraint errors. If you need custom error messages, you can still handle them explicitly:
+If you need a custom message for one constraint, catch it explicitly and re-throw everything else:
 
 ```typescript
-import { DefaultCRUDRepository } from '@venizia/ignis';
+import { DefaultCRUDRepository, type TCount } from '@venizia/ignis';
 import { getError, HTTP } from '@venizia/ignis-helpers';
 
 export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
-  async createWithCustomError(data: TCreateUser): Promise<TCreateResult<TUser>> {
+  async createWithCustomError(data: TCreateUser): Promise<TCount & { data: TUser }> {
     try {
       return await this.create({ data });
     } catch (error) {
@@ -196,43 +269,45 @@ export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
 }
 ```
 
-## 4. Global Error Handler
+## Customize the global handler
 
-IGNIS includes a built-in error handler. Customize behavior in your application:
+IGNIS wires a built-in handler by default. `AppErrorMiddleware` from `@venizia/ignis` is a class, registered as `new AppErrorMiddleware({ logger, rootKey }).value()`, and `value()` returns the Hono `ErrorHandler`. You rarely need to replace it. When you do, keep the same response contract:
 
 ```typescript
 import { BaseApplication } from '@venizia/ignis';
-import { ApplicationError, MessageCode } from '@venizia/ignis-helpers';
+import { isApplicationError, MessageCode } from '@venizia/ignis-helpers';
 
 export class Application extends BaseApplication {
   override setupMiddlewares(): void {
     super.setupMiddlewares();
 
-    // Custom error handler (optional)
-    this.server.onError((error, c) => {
+    // Custom error handler (optional) - the default AppErrorMiddleware already does this.
+    // `this.server` is `{ hono, runtime, instance }` - reach the Hono app via getServer().
+    this.getServer().onError((error, c) => {
       const requestId = c.get('requestId') ?? 'unknown';
 
       // Log all errors
-      this.logger.error('[%s] Error | %s', requestId, error.message);
+      this.logger.error('[%s] Error | %s', requestId, error);
 
-      // Handle known application errors
-      if (error instanceof ApplicationError) {
+      // Handle known application errors - isApplicationError(), never `instanceof
+      // ApplicationError` (unreliable across package boundaries)
+      if (isApplicationError(error)) {
         return c.json({
           statusCode: error.statusCode,
           message: error.message,
-          messageCode: error.messageCode, // already lower-cased, never undefined
-          details: error.details,
+          normalized: error.normalized, // { text, code, args } - never undefined
+          extra: error.extra,
           requestId,
-        }, error.statusCode as StatusCode);
+        }, error.statusCode as Parameters<typeof c.json>[1]);
       }
 
-      // Handle Zod validation errors
+      // Handle Zod validation errors - Zod v4 exposes `issues`, not `errors`
       if (error.name === 'ZodError') {
         return c.json({
           statusCode: 422,
           message: 'Validation failed',
-          messageCode: MessageCode.DEFAULT,
-          details: { cause: error.errors },
+          normalized: { text: 'Validation failed', code: MessageCode.DEFAULT, args: {} },
+          details: { cause: error.issues },
           requestId,
         }, 422);
       }
@@ -241,7 +316,7 @@ export class Application extends BaseApplication {
       return c.json({
         statusCode: 500,
         message: 'Internal server error',
-        messageCode: MessageCode.DEFAULT,
+        normalized: { text: 'Internal server error', code: MessageCode.DEFAULT, args: {} },
         requestId,
       }, 500);
     });
@@ -249,59 +324,67 @@ export class Application extends BaseApplication {
 }
 ```
 
-## 5. Error Response Format
-
-All errors should follow a consistent format:
+## The error response shape
 
 ```typescript
 interface ErrorResponse {
   statusCode: number;
   message: string;
-  messageCode?: string; // stable, localizable code (validation: from params.code or the raw Zod code)
+  normalized: {
+    text: string;
+    code: string; // stable, localizable code (validation: from params.code or the raw Zod code)
+    args: Record<string, unknown>;
+  };
   requestId: string;
   extra?: Record<string, unknown>; // structured context attached via getError(...)
-  details?: {
-    cause?: Array<{
-      path: string;
-      message: string;
-      code: string;
-    }>;
+  details: {
+    url: string;
+    path: string;
+    stack?: string; // non-production only
+    cause?: unknown; // non-production only, or the Zod issue list for 422s
     [key: string]: unknown;
   };
 }
 ```
 
-**Example Responses:**
+There's no top-level `messageCode` - read `normalized.code`. `extra` never mirrors `messageArgs`; the resolved interpolation values live at `normalized.args`.
+
+**400 Bad Request:**
 
 ```json
-// 400 Bad Request
 {
-  "statusCode": 400,
   "message": "Invalid request body",
-  "messageCode": "core.system_error",
-  "requestId": "abc123"
+  "statusCode": 400,
+  "normalized": { "text": "Invalid request body", "code": "core.system_error", "args": {} },
+  "requestId": "abc123",
+  "details": { "url": "http://localhost:3000/users", "path": "/users" }
 }
+```
 
-// 404 Not Found
-// Extra keys passed to getError(...) (e.g. `details`) surface under `extra`;
-// the top-level `details` object is reserved for middleware context (url, path, stack, cause).
+**404 Not Found:** extra keys passed to `getError(...)` (for example `details`) surface under the top-level `extra`. The top-level `details` object is reserved for middleware context (url, path, stack, cause) - the two never share a key.
+
+```json
 {
-  "statusCode": 404,
   "message": "User not found",
-  "messageCode": "core.system_error",
+  "statusCode": 404,
+  "normalized": { "text": "User not found", "code": "core.system_error", "args": {} },
   "requestId": "abc123",
-  "extra": { "details": { "id": "user-uuid" } }
+  "extra": { "details": { "id": "user-uuid" } },
+  "details": { "url": "http://localhost:3000/users/user-uuid", "path": "/users/:id" }
 }
+```
 
-// 422 Validation Error
-// `message`/`messageCode` come from the first failing issue - its `params.code` if the schema set
-// one, otherwise the raw Zod code (e.g. `invalid_type`, `too_small`). The full list stays in `details.cause`.
+**422 Validation Error:** `message` and `normalized.code` come from the first failing issue - its `params.code` if the schema set one, otherwise the raw Zod code (for example `invalid_type`, `too_small`). `normalized.args` is always empty for a Zod issue; the full list of issues stays in `details.cause`.
+
+```json
 {
-  "statusCode": 422,
   "message": "Invalid email format",
-  "messageCode": "user.email.invalid",
+  "statusCode": 422,
+  "normalized": { "text": "Invalid email format", "code": "user.email.invalid", "args": {} },
   "requestId": "abc123",
   "details": {
+    "url": "http://localhost:3000/users",
+    "path": "/users",
     "cause": [
       {
         "path": "email",
@@ -311,55 +394,50 @@ interface ErrorResponse {
     ]
   }
 }
-
-// 500 Internal Error (production)
-{
-  "statusCode": 500,
-  "message": "Internal server error",
-  "messageCode": "core.system_error",
-  "requestId": "abc123"
-}
 ```
 
-## 6. Logging Errors
+## Log errors
 
-### `%s`, Never `%j`, for an `Error`
+### Use `%s`, never `%j`, for an Error
 
-`message` and `stack` are non-enumerable properties on a native `Error` (and on `ApplicationError`, which extends it). `%j` serializes via `JSON.stringify`, which only visits enumerable own properties - so `logger.error('... | error: %j', error)` silently drops both `message` and `stack`, logging little more than `{}`. Always use `%s` to log an `Error` instance; reserve `%j`/`%o` for plain data objects.
+`message` and `stack` are non-enumerable properties on a native `Error` (and on `ApplicationError`, which extends it). `%j` serializes via `JSON.stringify`, which only visits enumerable own properties - so `logger.error('... | error: %j', error)` silently drops both. Always use `%s` to log an `Error` instance; reserve `%j`/`%o` for plain data objects.
 
 ```typescript
-// ✅ Good - %s prints message + stack
+// Good - %s prints message + stack
 this.logger.error('[createOrder] Failed | error: %s', error);
 
-// ❌ Bad - %j drops message and stack (non-enumerable)
+// Bad - %j drops the stack
 this.logger.error('[createOrder] Failed | error: %j', error);
 ```
 
-### What to Log
+> [!NOTE]
+> An `ApplicationError` logged with `%j` does show its message text, because the text rides inside the enumerable `normalized.text`. That's incidental, not a reprieve - the **stack** is still gone, which is the reason the rule exists. A plain `Error` under `%j` still logs little more than `{}`.
+
+### What to log
 
 ```typescript
-// ✅ Good - Context for debugging
+// Good - context for debugging. `%s` on the error itself carries message + stack
 this.logger.error('[createOrder] Failed | userId: %s | orderId: %s | error: %s',
-  userId, orderId, error.message);
-
-// ✅ Good - Include stack trace for unexpected errors
-this.logger.error('[createOrder] Unexpected error | %s', error.stack);
+  userId, orderId, error);
 
-// ❌ Bad - No context
+// Bad - no context, and `.message` throws the stack away
 this.logger.error(error.message);
 
-// ❌ Bad - Sensitive data
+// Bad - sensitive data
 this.logger.error('Login failed for user | password: %s', password);
 ```
 
-### Log Levels
+### Log levels
+
+`ILogger` has exactly five levels, each a direct method. `alert`, `http`, `verbose`, and `silly` don't exist.
 
-| Level | Use For |
+| Level | Use for |
 |-------|---------|
+| `emerg` | The process cannot continue - unrecoverable |
 | `error` | Exceptions that need attention |
 | `warn` | Recoverable issues, deprecation warnings |
 | `info` | Important business events |
-| `debug` | Detailed debugging information |
+| `debug` | Detailed debugging information (gated on `DEBUG`) |
 
 ```typescript
 // Error - requires attention
@@ -375,85 +453,95 @@ this.logger.info('[order] Created | orderId: %s | userId: %s', orderId, userId);
 this.logger.debug('[query] Executing | sql: %s | params: %j', sql, params);
 ```
 
-## 7. Async Error Handling
+## Handle async errors
 
 ### Promises
 
+`async`/`await` propagates errors on its own - most of the time, you write no error handling at all.
+
 ```typescript
-// ✅ Good - Errors propagate naturally with async/await
-async function processOrder(orderId: string) {
+// Good - errors propagate naturally with async/await
+const processOrder = async (orderId: string) => {
   const order = await orderRepository.findById({ id: orderId }); // Throws if fails
-  const payment = await paymentService.charge(order); // Throws if fails
-  return payment;
-}
+  return paymentService.charge(order); // Throws if fails
+};
 
-// ✅ Good - Explicit catch when you need to handle
-async function processOrderWithFallback(orderId: string) {
+// Good - explicit catch when you need to handle
+const processOrderWithFallback = async (order: TOrder) => {
   try {
     return await paymentService.charge(order);
   } catch (error) {
-    this.logger.warn('[processOrder] Primary payment failed, trying backup');
-    return await backupPaymentService.charge(order);
+    this.logger.warn('[processOrder] Primary payment failed, trying backup | error: %s', error);
+    return backupPaymentService.charge(order);
   }
-}
+};
 
-// ❌ Bad - Swallowing errors
-async function processOrder(orderId: string) {
+// Bad - swallowing errors
+const processOrderSilently = async () => {
   try {
     await dangerousOperation();
   } catch (error) {
     // Error is swallowed - no one knows it happened!
   }
-}
+};
 ```
 
-### Fire-and-Forget with Error Handling
+### Fire-and-forget
+
+But a call you don't `await` needs its own `.catch()`, or a rejection crashes the process as an unhandled rejection.
 
 ```typescript
-// ✅ Good - Log errors from fire-and-forget operations
+// Good - log errors from fire-and-forget operations
 this.sendNotification(userId).catch(error => {
-  this.logger.error('[notify] Failed | userId: %s | error: %s', userId, error.message);
+  this.logger.error('[notify] Failed | userId: %s | error: %s', userId, error);
 });
 
-// ✅ Good - Use void to indicate intentional fire-and-forget
+// Good - use void to indicate intentional fire-and-forget
 void this.analytics.track('order_created', { orderId });
 
-// ❌ Bad - Unhandled promise rejection
+// Bad - unhandled promise rejection
 this.sendNotification(userId); // If this rejects, crash!
 ```
 
-## 8. Transaction Error Handling
+## Roll back a transaction on failure
 
 ```typescript
-async function transferFunds(from: string, to: string, amount: number) {
-  const tx = await accountRepository.beginTransaction();
+import { getError, HTTP } from '@venizia/ignis-helpers';
+
+const transferFunds = async (opts: { from: string; to: string; amount: number }) => {
+  const { from, to, amount } = opts;
+  const transaction = await accountRepository.beginTransaction();
 
   try {
-    await accountRepository.debit({ id: from, amount, options: { transaction: tx } });
-    await accountRepository.credit({ id: to, amount, options: { transaction: tx } });
+    await accountRepository.debit({ id: from, amount, options: { transaction } });
+    await accountRepository.credit({ id: to, amount, options: { transaction } });
 
-    await tx.commit();
+    await transaction.commit();
     return { success: true };
   } catch (error) {
-    await tx.rollback();
+    await transaction.rollback();
 
     // Re-throw with context
     throw getError({
       statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
       message: '[transferFunds] Transaction failed',
-      details: { from, to, amount, originalError: error.message },
+      cause: error,
+      extra: { from, to, amount },
     });
   }
-}
+};
 ```
 
-## 9. Client-Side Error Handling
+> [!NOTE]
+> `rollback()` throws on failure, so it belongs in the `catch` block exactly as shown here - never after a `commit()` you already awaited outside one. A rollback that follows a **failed** commit is a deliberate no-op: the transaction is already torn down, so this canonical shape stays safe.
+
+## Parse errors on the client
 
-Guide for API consumers:
+Branch on `normalized.code` - it's always present. There's no top-level `messageCode`.
 
 ```typescript
 // TypeScript client example
-async function createUser(data: CreateUserRequest): Promise<User> {
+const createUser = async (data: TCreateUserRequest): Promise<TUser> => {
   const response = await fetch('/api/users', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
@@ -464,38 +552,44 @@ async function createUser(data: CreateUserRequest): Promise<User> {
     const error = await response.json();
 
     switch (response.status) {
-      case 400:
-        throw new ValidationError(error.message, error.details);
-      case 401:
-        // Redirect to login
+      case 400: {
+        // Context passed to getError(...) arrives under `extra`, not `details`
+        throw new ValidationError(error.message, error.extra);
+      }
+      case 401: {
         window.location.href = '/login';
         throw new AuthError('Please log in');
-      case 404:
+      }
+      case 404: {
         throw new NotFoundError(error.message);
-      case 422:
-        // Handle field-level errors
-        const fieldErrors = error.details?.cause?.reduce((acc, e) => {
-          acc[e.path] = e.message;
-          return acc;
+      }
+      case 422: {
+        // Field-level issues live in details.cause
+        const fieldErrors = error.details?.cause?.reduce((accumulator, issue) => {
+          accumulator[issue.path] = issue.message;
+          return accumulator;
         }, {});
-        throw new ValidationError('Validation failed', fieldErrors);
-      case 429:
+        throw new ValidationError(error.normalized.code, fieldErrors);
+      }
+      case 429: {
         throw new RateLimitError('Too many requests. Try again later.');
-      default:
+      }
+      default: {
         throw new ApiError(error.message || 'Something went wrong');
+      }
     }
   }
 
   return response.json();
-}
+};
 ```
 
-## Error Handling Checklist
+## Checklist
 
 | Category | Check |
 |----------|-------|
 | **Services** | Business rule violations throw appropriate errors |
-| **Repositories** | Database errors are caught and wrapped |
+| **Repositories** | Constraint errors left to the global handler; only custom messages wrapped |
 | **Controllers** | Errors propagate to global handler |
 | **Async** | All promises have error handling |
 | **Transactions** | Always rollback on error |
@@ -503,7 +597,7 @@ async function createUser(data: CreateUserRequest): Promise<User> {
 | **Responses** | Consistent error format returned |
 | **Security** | No sensitive data in error messages |
 
-## See Also
+## See also
 
 - [Common Pitfalls](./common-pitfalls) - Error handling mistakes
 - [Testing Strategies](./testing-strategies) - Testing error scenarios