@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/extensions/helpers/error/index.md

@@ -1,27 +1,14 @@
-# Error
-
-Standardized error class and factory for throwing HTTP-aware errors with machine-readable codes across the application.
-
-## Quick Reference
+---
+title: Error
+description: ApplicationError, the getError factory, and a catalog pattern for machine-readable error codes
+difficulty: beginner
+---
 
-| Item | Value |
-|------|-------|
-| **Package** | `@venizia/ignis-helpers` |
-| **Class** | `ApplicationError` |
-| **Extends** | `Error` (native) |
-| **Runtimes** | Both |
-
-#### Import Paths
-
-```typescript
-import { ApplicationError, getError, isApplicationError } from '@venizia/ignis-helpers';
-import { ErrorSchema } from '@venizia/ignis-helpers';
-import type { TError } from '@venizia/ignis-helpers';
-```
+# Error
 
-## Creating an Instance
+`getError()` builds an `ApplicationError` carrying an HTTP status and a machine-readable code - the house rule is `getError`, never `new Error`.
 
-The canonical way to raise an error in IGNIS is the standalone `getError()` factory - use it everywhere (house rule: `getError`, never `new Error`). `ApplicationError` extends the native `Error` class with an HTTP `statusCode` and an optional `messageCode` for machine-readable error identification; `getError()` constructs one for you.
+## In one example
 
 ```typescript
 import { getError, HTTP } from '@venizia/ignis-helpers';
@@ -33,251 +20,278 @@ throw getError({
 });
 ```
 
-#### Options (`TError`)
-
-The same options apply to `getError()`, the `ApplicationError` constructor, and the static factory:
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `message` | `string` | -- (required) | Human-readable error message |
-| `statusCode` | `number` | `400` | HTTP status code |
-| `messageCode` | `string` | `MessageCode.DEFAULT` (`'core.system_error'`) | Machine-readable error code for client-side handling. Always resolved through `MessageCode.resolve()` -- never left `undefined`, and lower-cased regardless of what was passed in |
-| `name` | `string` | `undefined` | Accepted by the schema but discarded by the constructor (the native `Error` name is kept) |
+The framework's `AppErrorMiddleware` catches `ApplicationError` instances and formats them into a consistent JSON response - see [Common tasks](#common-tasks) below.
+
+## How it works
+
+- **Three equivalent entry points.** `getError(opts)`, `new ApplicationError(opts)`, and the static `ApplicationError.getError(opts)` all take the same input and build the same object - use the class form only when a direct reference reads better.
+- **Two input shapes.** Free-form (`{ message, statusCode?, messageCode? }`) covers one-off failures - most throw sites. Catalogued (`{ error: TErrorDefinition }`) raises a failure declared once at module scope, so its code, status, and default text cannot drift across the call sites that raise it.
+- **One message shape everywhere.** `message` is either the historical string (with sibling `messageCode?`/`messageArgs?`) or an object mirroring `normalized`: `{ text, code?, args? }`. Both resolve to the same `normalized`:
+
+  ```typescript
+  getError({ message: 'Only %{n} left', messageCode: 'stock.low', messageArgs: { n: 2 } }); // flat
+  getError({ message: { text: 'Only %{n} left', code: 'stock.low', args: { n: 2 } } });     // nested
+  getError({ error: StockErrors.LOW, messageArgs: { n: 2 } });                              // catalogued
+  ```
+
+  On the catalogued form, `message` is a **partial** override - `{ message: { args } }` amends just the args and keeps the definition's `text`/`code`.
+- **Precedence, most specific first.** `code`: `message.code` -> the definition's `message.code` -> `messageCode`. `args`: `message.args` -> `messageArgs` -> the definition's `message.args`.
+- **`messageCode` always resolves to something.** `MessageCode.resolve()` lower-cases it and falls back to `MessageCode.DEFAULT` (`'core.system_error'`) when none is given or it is empty - `error.normalized.code` is never `undefined`.
+- **`normalized` is the single source, and there is no flat duplicate.** `{ text, code, args }` - `text` defaults to `message`, `code`/`args` resolve per the precedence above. `args` is always populated (`{}` when empty), so no consumer needs a null check. A client renders any error with one lookup: `translate(error.normalized.code, error.normalized.args)`. `messageCode` and `messageArgs` are INPUTS only: there is no `error.messageCode` field, and `extra` never mirrors `messageArgs`. Pass `transform` to build `normalized` yourself in place of the default.
+- **Any key the input does not declare rides into `extra`.** Attach whatever context your clients need - `getError({ message, transaction: {...} })` lands at `error.extra.transaction`. Passing `extra` explicitly works too, and the two merge with the explicit one winning. `extra` carries caller context ONLY; it is `undefined` when there is nothing to carry.
+- **`cause` reaches the native `Error.cause`,** not `extra` - wrap a lower-level failure with `getError({ message, cause: originalError })` and every tool that reads `.cause` sees it. `error` is **refused** on the free-form branch (`error?: never`) precisely so this mistake fails at compile time: `getError({ message, error: caughtError })` does not compile - use `cause`.
+- **`isApplicationError()` checks shape, not class identity.** There is one `ApplicationError` - it lives in `@venizia/ignis-inversion` so a browser application can raise and read the same errors the server does, and `helpers` re-exports it. `instanceof` still fails across a package boundary: inversion ships dual CJS+ESM builds, so one source class has two runtime constructors. Test the shape.
+
+**Options shared by both forms**
+
+| Option          | Type                                  | Description                                                                                                     |
+| --------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `message`       | `string \| { text, code?, args? }`     | Required on the free-form branch; a **partial** override on the catalogued branch (definition supplies what's omitted) |
+| `messageCode`   | `string`                               | Free-form only, sibling to a string `message`. Lowest precedence - `message.code` and the definition's `message.code` both win over it |
+| `statusCode`    | `number`                               | Defaults to `400`, or the definition's `statusCode` for the catalogued form                                     |
+| `messageArgs`   | `Record<string, unknown>`              | Interpolation values. Reaches `normalized.args` - never `extra`. Lowest precedence, same rule as `messageCode`  |
+| `cause`         | `unknown`                              | The wrapped failure - reaches `Error.cause`. Use this to wrap a caught error; `error` is refused on the free-form branch for exactly this case |
+| `extra`         | `Record<string, unknown>`              | Explicit context, merged with any swept keys - and it wins on a clash                                           |
+| `transform`     | `TErrorNormalizeTransformFn`           | Builds `normalized` in place of the default. Receives `{ message: TErrorNormalized, statusCode, extra? }` - `message` is the default normalized being replaced, so `s => ({ ...s.message, text: 'x' })` amends one field |
+| _anything else_ | `unknown`                              | Rides into `extra` under its own name. `getError({ message, transaction })` lands at `error.extra.transaction`  |
 
 > [!TIP]
-> The `TError` type is derived from `ErrorSchema` (a Zod schema) and uses `.catchall(z.any())`, so you can pass additional arbitrary properties beyond the four listed above. Extra properties are collected into the `extra` field on the resulting `ApplicationError` instance.
+> Spreading a definition now resolves identically to passing it as `error`: `getError({ ...CategoryErrors.CREATE_DUPLICATE_NAME })` and `getError({ error: CategoryErrors.CREATE_DUPLICATE_NAME })` build the same `ApplicationError`. A definition's `message` is `{ text, code, args? }` - the same shape the free-form input accepts - so the spread degrades to nothing. Prefer `{ error: DEF }` anyway; it reads as "raise this catalogued error" instead of "raise these loose fields."
 
-#### `ApplicationError` Constructor and Static Factory
+## Every shape and its output
 
-`getError()` is the canonical form. The class constructor and the static `ApplicationError.getError()` are legal equivalents - use them only when a direct class reference reads better:
+Every row below is the real output, and the catalogued rows all use this definition:
 
 ```typescript
-import { ApplicationError, HTTP } from '@venizia/ignis-helpers';
-
-// Class constructor (equivalent to getError)
-const error = new ApplicationError({
-  message: 'Configuration missing',
-  statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
-});
-
-// Static factory (equivalent to getError)
-throw ApplicationError.getError({
-  message: 'Invalid credentials',
-  statusCode: HTTP.ResultCodes.RS_4.Unauthorized,
-  messageCode: 'core.auth.invalid_credentials',
-});
+const DEF = {
+  message: {
+    text: 'A category named "%{name}" already exists.',
+    code: 'server.commerce.category.duplicate',
+    args: { name: '?' },
+  },
+  statusCode: 409,
+} as const satisfies TErrorDefinition;
 ```
 
-### MessageCode
+**Free-form, flat** - the historical shape, unchanged:
 
-`MessageCode` builds and normalizes the machine-readable codes carried on `ApplicationError.messageCode`. Every code an application throws should be constructed with `MessageCode.build()` rather than typed as a raw string literal -- a malformed code fails at module load (import time) instead of shipping dead into production.
+| Input | `message` | `statusCode` | `normalized` |
+|-------|-----------|--------------|--------------|
+| `{ message: 'Broke' }` | `Broke` | `400` | `{ text: 'Broke', code: 'core.system_error', args: {} }` |
+| `{ message: 'Broke', messageCode: 'a.b' }` | `Broke` | `400` | `{ text: 'Broke', code: 'a.b', args: {} }` |
+| `{ message: 'Only %{n} left', messageArgs: { n: 2 } }` | `Only %{n} left` | `400` | `{ text: 'Only %{n} left', code: 'core.system_error', args: { n: 2 } }` |
+| `{ message, messageCode: 'stock.low', messageArgs: { n: 2 }, statusCode: 409 }` | `Only %{n} left` | `409` | `{ text: 'Only %{n} left', code: 'stock.low', args: { n: 2 } }` |
 
-```typescript
-import { MessageCode } from '@venizia/ignis-helpers';
+**Free-form, object** - `text` is the only required field. Each row is identical to its flat twin above:
 
-export class UserErrorCodes {
-  static readonly NOT_FOUND = MessageCode.build({ parts: ['core', 'user', 'not_found'] });
-  static readonly DUPLICATE_EMAIL = MessageCode.build({ parts: ['core', 'user', 'duplicate_email'] });
-}
-```
+| Input | `normalized` |
+|-------|--------------|
+| `{ message: { text: 'Broke' } }` | `{ text: 'Broke', code: 'core.system_error', args: {} }` |
+| `{ message: { text: 'Broke', code: 'a.b' } }` | `{ text: 'Broke', code: 'a.b', args: {} }` |
+| `{ message: { text: 'Only %{n} left', code: 'stock.low', args: { n: 2 } } }` | `{ text: 'Only %{n} left', code: 'stock.low', args: { n: 2 } }` |
 
-| Member | Type | Value / Signature | Description |
-|--------|------|--------------------|-------------|
-| `DEFAULT` | `string` | `'core.system_error'` | The code `ApplicationError` falls back to when no `messageCode` is supplied |
-| `SEPARATOR` | `string` | `'.'` | Joins segments into a dotted code (e.g. `core.mail.send_failed`) |
-| `SEGMENT_PATTERN` | `RegExp` | `/^[a-z0-9]+(_[a-z0-9]+)*$/` | Each segment must be lower snake_case -- `a-z`, `0-9`, `_` |
-| `MIN_SEGMENTS` | `number` | `2` | A code needs at least a namespace and a reason (e.g. `core.not_found` is valid, `not_found` alone is not) |
-| `build(opts: { parts: Array<string> })` | `string` | -- | Joins `parts` with `SEPARATOR` and lower-cases the result. Throws (via `getError`) if `parts.length < MIN_SEGMENTS`, or if any segment fails `SEGMENT_PATTERN` |
-| `isValid(code: string)` | `boolean` | -- | Cheap structural check for a code arriving from outside the process |
-| `resolve(code?: string)` | `string` | -- | Normalizes an absent or empty code to `DEFAULT`; otherwise lower-cases `code` |
+**Catalogued** - omit a field and the definition supplies it:
 
-> [!IMPORTANT]
-> `ApplicationError`'s constructor always calls `MessageCode.resolve(messageCode)` -- so `error.messageCode` is **never** `undefined`, and it is **always lower-cased** regardless of the casing passed to `getError()`. A comparison like `error.messageCode === 'DUPLICATE_EMAIL'` is always false; compare against `'duplicate_email'` (or the exact string returned by `MessageCode.build()`).
+| Input | `message` | `statusCode` | `normalized.code` | `normalized.args` |
+|-------|-----------|--------------|-------------------|-------------------|
+| `{ error: DEF }` | the definition's text | `409` | `server.commerce.category.duplicate` | `{ name: '?' }` |
+| `{ error: DEF, messageArgs: { name: 'Vé' } }` | the definition's text | `409` | `server.commerce.category.duplicate` | `{ name: 'Vé' }` |
+| `{ error: DEF, message: { args: { name: 'Vé' } } }` | the definition's text | `409` | `server.commerce.category.duplicate` | `{ name: 'Vé' }` |
+| `{ error: DEF, message: { text: 'Custom' } }` | `Custom` | `409` | `server.commerce.category.duplicate` | `{ name: '?' }` |
+| `{ error: DEF, message: { code: 'override.code' } }` | the definition's text | `409` | `override.code` | `{ name: '?' }` |
+| `{ error: DEF, message: 'Custom' }` | `Custom` | `409` | `server.commerce.category.duplicate` | `{ name: '?' }` |
+| `{ error: DEF, statusCode: 410 }` | the definition's text | `410` | `server.commerce.category.duplicate` | `{ name: '?' }` |
+| `{ ...DEF }` (spread) | the definition's text | `409` | `server.commerce.category.duplicate` | `{ name: '?' }` |
 
-## Checking for an Application Error
+**Context and cause:**
 
-Use `isApplicationError(error)` to recognize an application error by **shape** - an `Error` instance carrying a numeric `statusCode` - rather than by class identity:
+| Input | Output |
+|-------|--------|
+| `{ message, extra: { categoryId: 42 } }` | `extra: { categoryId: 42 }` |
+| `{ message, userId: 7, transaction: { id: 12 } }` | `extra: { userId: 7, transaction: { id: 12 } }` - swept |
+| `{ message, userId: 7, extra: { userId: 9 } }` | `extra: { userId: 9 }` - explicit wins |
+| `{ message, cause: err }` | `Error.cause = err`; `extra` stays `undefined` |
+| `{ message, error: caughtError }` | **does not compile** - use `cause` |
 
-```typescript
-import { isApplicationError } from '@venizia/ignis-helpers';
+**Transform** - `message` in the snapshot IS the default being replaced:
 
-try {
-  await someOperation();
-} catch (error) {
-  if (isApplicationError(error)) {
-    // already shaped (has a statusCode) - surface as-is
-    throw error;
-  }
-  // an unknown failure - sanitize before rethrowing
-  throw getError({ message: 'Operation failed', statusCode: HTTP.ResultCodes.RS_5.InternalServerError });
-}
+```typescript
+getError({
+  message: { text: 'Only %{n} left', code: 'stock.low', args: { n: 2 } },
+  transform: snapshot => ({ ...snapshot.message, text: 'Chỉ còn 2 vé.' }),
+});
+// error.message           -> 'Only %{n} left'   (the raw text stays)
+// error.normalized.text   -> 'Chỉ còn 2 vé.'
+// error.normalized.code   -> 'stock.low'
+// error.normalized.args   -> { n: 2 }
 ```
 
-> [!WARNING]
-> Never compare `ApplicationError` with `instanceof` across a package boundary. `inversion` ships **dual CJS + ESM** builds (its DI powers frontend libraries), so its error class deliberately has more than one runtime identity, and `helpers` keeps its own `ApplicationError` for the backend stack. Two objects that are both "an application error" can be instances of different classes, so `instanceof` gives false negatives. `isApplicationError` checks the shape and works regardless of which package threw. The search connectors use it to decide what is already shaped versus what must be sanitized as a `503`.
-
-## Usage
-
-### Throwing Errors in Services
+**Precedence,** most specific first - note a definition's `message.code` beats a flat `messageCode`:
 
-The most common pattern is throwing `ApplicationError` from service methods to signal HTTP-level failures. The framework's error handling middleware catches these and formats the response automatically.
+| Resolves | Order |
+|----------|-------|
+| `normalized.code` | `message.code` -> the definition's `message.code` -> `messageCode` -> `MessageCode.DEFAULT` |
+| `normalized.args` | `message.args` -> `messageArgs` -> the definition's `message.args` -> `{}` |
+| `normalized.text` | `message.text` (or a string `message`) -> the definition's `message.text` -> `''` |
+| `statusCode` | `statusCode` -> the definition's `statusCode` -> `400` |
 
-```typescript
-import { getError, HTTP } from '@venizia/ignis-helpers';
-
-class AuthenticationService {
-  async signUp(opts: { username: string; credential: string }) {
-    const existingUser = await this.userRepository.findByUsername(opts.username);
-    if (existingUser) {
-      throw getError({
-        statusCode: HTTP.ResultCodes.RS_4.Conflict,
-        message: 'Username already exists',
-      });
-    }
-    // ...
-  }
-}
-```
+## Common tasks
 
-### Using `messageCode` for Client-Side Handling
+### Throw a free-form error
 
-The `messageCode` field allows frontend applications to map errors to localized messages or specific UI behaviors without parsing the human-readable `message` string.
+The most common shape - a `message` and a status.
 
 ```typescript
 throw getError({
-  message: 'Email verification required before login',
-  statusCode: HTTP.ResultCodes.RS_4.Forbidden,
-  messageCode: 'auth.email_not_verified',
+  statusCode: HTTP.ResultCodes.RS_4.Conflict,
+  message: 'Username already exists',
 });
 ```
 
-### Error Response Format
+### Recognize an already-shaped error in a catch block
 
-The built-in `appErrorHandler` middleware (from `@venizia/ignis`) catches `ApplicationError` instances and formats them into consistent JSON responses. The response shape differs by environment.
-
-#### Sanitized (Production-Class) Response
-
-The handler is **fail-closed**: it exposes internals only when `NODE_ENV` names a development environment - one of `local`, `debug`, `development`, `dev`, `sit` (`Environment.DEVELOPMENT_ENVS`). Everything else is sanitized as production: `production`, and also `alpha`, `beta`, `uat`, `staging`, an unrecognized name, and an unset `NODE_ENV`.
-
-In a sanitized response, `stack` and `cause` are omitted from `details`. For unexpected errors without a `statusCode` (i.e., not thrown via `getError`), the raw message is replaced with a generic `"Internal Server Error"`, and a database error keeps only its base message - no SQL detail, no table or constraint name.
-
-```json
-{
-  "message": "User not found",
-  "messageCode": "core.user.not_found",
-  "statusCode": 404,
-  "requestId": "abc-123-def",
-  "details": {
-    "url": "http://localhost:3000/api/users/123",
-    "path": "/api/users/123"
-  }
-}
-```
-
-#### Development Response
-
-In a development environment (see the list above), `details` additionally includes debugging fields:
+```typescript
+import { isApplicationError } from '@venizia/ignis-helpers';
 
-```json
-{
-  "message": "User not found",
-  "messageCode": "core.user.not_found",
-  "statusCode": 404,
-  "requestId": "abc-123-def",
-  "details": {
-    "url": "http://localhost:3000/api/users/123",
-    "path": "/api/users/123",
-    "stack": "Error: User not found\n    at ...",
-    "cause": "..."
+try {
+  await someOperation();
+} catch (error) {
+  if (isApplicationError(error)) {
+    throw error; // already shaped - surface as-is
   }
+  throw getError({
+    message: 'Operation failed',
+    statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+  });
 }
 ```
 
-### ErrorSchema (Zod)
+### Catalog a reusable error
 
-`ErrorSchema` is a Zod object schema used for OpenAPI response documentation. It is typically referenced in route definitions to describe error responses.
+Declare it once; every call site raises it by reference instead of retyping the code and status.
 
 ```typescript
-import { ErrorSchema, HTTP } from '@venizia/ignis-helpers';
-
-// In route definition responses
-const responses = {
-  [HTTP.ResultCodes.RS_4.NotFound]: {
-    description: 'Resource not found',
-    content: {
-      'application/json': { schema: ErrorSchema },
+import { ErrorScopes, getError, HTTP } from '@venizia/ignis-helpers';
+import type { TErrorDefinition } from '@venizia/ignis-helpers';
+
+const CategoryErrors = {
+  CREATE_DUPLICATE_NAME: {
+    message: {
+      text: 'A category named "%{name}" already exists.',
+      code: 'server.commerce.category.create.duplicate_name',
     },
+    statusCode: HTTP.ResultCodes.RS_4.Conflict,
+    category: ErrorScopes.VALIDATION,
   },
-};
+} as const satisfies Record<string, TErrorDefinition>;
+
+throw getError({ error: CategoryErrors.CREATE_DUPLICATE_NAME, messageArgs: { name: 'Vé' } });
+// Equivalent, using the catalogued form's partial override instead:
+throw getError({ error: CategoryErrors.CREATE_DUPLICATE_NAME, message: { args: { name: 'Vé' } } });
 ```
 
-The schema shape:
+`ErrorScopes` groups a failure by intent - `AUTH`, `VALIDATION`, `BUSINESS`, `SYSTEM`, `INTEGRATION` - because `statusCode` cannot: a `409` is a business conflict in one place and a validation clash in another.
 
-```typescript
-const ErrorSchema = z
-  .object({
-    name: z.string().optional(),
-    statusCode: z.number().optional(),
-    messageCode: z.string().optional(),
-    message: z.string(),
-  })
-  .catchall(z.any());
-```
+> [!WARNING]
+> `category` is catalog **metadata only** - it does not reach the error response. `getError` reads `message.text`, `message.code` and `statusCode` off a definition and ignores the rest. Use it to group and filter catalogs (ops dashboards, translator exports); do not expect a client to receive it.
 
-### Common Status Code Patterns
+### Register catalog keys for `messageCode` autocomplete
 
-| Scenario | Status Code | `HTTP.ResultCodes` Path |
-|----------|-------------|-------------------------|
-| Invalid input / bad request | 400 | `RS_4.BadRequest` |
-| Missing or invalid auth | 401 | `RS_4.Unauthorized` |
-| Insufficient permissions | 403 | `RS_4.Forbidden` |
-| Resource not found | 404 | `RS_4.NotFound` |
-| Duplicate resource | 409 | `RS_4.Conflict` |
-| Validation error | 422 | `RS_4.UnprocessableEntity` |
-| Server failure | 500 | `RS_5.InternalServerError` |
+Augment the module the file already imports from. `IErrorKeyRegistry` is declared in `@venizia/ignis-inversion` and re-exported by `helpers`; merging follows the re-export, so either name populates the same registry.
 
-## Troubleshooting
+```typescript
+import type { TRegisterErrors } from '@venizia/ignis-helpers';
 
-### `statusCode` defaults to 400
+declare module '@venizia/ignis-helpers' {
+  interface IErrorKeyRegistry extends TRegisterErrors<typeof CategoryErrors> {}
+}
+```
+
+> [!WARNING]
+> TypeScript only treats `declare module` as an **augmentation** when the file imports that module. Name a module the file never imports and it silently becomes an inert ambient declaration - no error, no keys registered, autocomplete quietly empty.
 
-**Cause:** `getError()` was called without specifying a `statusCode`. The `ApplicationError` constructor defaults to `400` (Bad Request).
+Declare `message.code` as a literal string, not through `MessageCode.build()` - `build()` returns `string`, which would widen the registry to `Record<string, true>` and destroy the autocomplete.
 
-**Fix:** Always provide an explicit status code using `HTTP.ResultCodes`:
+### Build a code outside a catalog
+
+`MessageCode.build()` validates at import time instead of shipping a malformed code into production.
 
 ```typescript
-throw getError({
-  message: 'Resource not found',
-  statusCode: HTTP.ResultCodes.RS_4.NotFound,
-});
-```
+import { MessageCode } from '@venizia/ignis-helpers';
 
-### Error response missing `stack` and `cause`
+const NOT_FOUND = MessageCode.build({ parts: ['core', 'user', 'not_found'] });
+// 'core.user.not_found' - throws if a segment isn't lower snake_case, or fewer than 2 parts
+```
 
-**Cause:** `NODE_ENV` is not one of the development environments, so the handler sanitized the response (`url` and `path` are always included). Note this is what happens on `alpha`/`staging`, on a typo'd name, and when `NODE_ENV` is unset - not only on `production`.
+### Read the error response shape
 
-**Fix:** Set `NODE_ENV` to a development name - `development`, `dev`, `local`, `debug` or `sit`. Anything else stays sanitized by design.
+`AppErrorMiddleware` (from `@venizia/ignis`) routes every thrown value into one of five shapes. All five carry `message`, `statusCode`, `normalized` and `details`; only an intentional error can carry `extra`. The code lives at `normalized.code` - there is no flat `messageCode` on the response.
 
-### Errors returning 500 instead of expected status code
+| What was thrown                           | Status  | `normalized.code`                                        | `message`                                                             | `extra`                                               |
+| ----------------------------------------- | ------- | ------------------------------------------------------ | --------------------------------------------------------------------- | ----------------------------------------------------- |
+| `ZodError` (validation)                   | 422     | the first issue's `params.code`, else its raw Zod code | that issue's message; per-field list in `details.cause`               | never                                                 |
+| DB client error (SQLSTATE class 22/23/44) | 400     | `core.system_error`                                    | a fixed, safe summary - never the driver's text                       | never                                                 |
+| Transient DB conflict (40001/40P01)       | 409     | `database.conflict`                                    | a fixed retry message                                                 | never                                                 |
+| `getError(...)` - intentional             | its own | its own                                                | its own                                                               | when the throw site attached `extra` or unknown keys  |
+| Anything else                             | 500     | `core.system_error`                                    | `Internal Server Error` in production; the raw message in development | never                                                 |
 
-**Cause:** A plain `Error` (not `ApplicationError`) was thrown. The `appErrorHandler` middleware only reads `statusCode` from errors that have that property. Native `Error` instances default to `500`.
+Only the intentional branch reports what the throw site wrote. The other four **replace** the message, because a driver error carries SQL, schema and constraint names - and `normalized` is built from the replacement, so it can never leak what `message` just scrubbed.
 
-**Fix:** Use `getError()` or `new ApplicationError()` instead of `new Error()`:
+`rootKey` (e.g. `new AppErrorMiddleware({ logger, rootKey: 'error' }).value()`) nests any of these under that key.
 
-```typescript
-// Incorrect -- will return 500
-throw new Error('Not found');
+The handler is fail-closed on environment: it exposes `stack` and `cause` in `details` only when `NODE_ENV` is one of `local`, `debug`, `development`, `dev`, `sit` (`Environment.DEVELOPMENT_ENVS`). Everything else - including `alpha`, `staging`, a typo, or an unset `NODE_ENV` - gets the sanitized shape:
 
-// Correct -- will return 404
-throw getError({
-  message: 'Not found',
-  statusCode: HTTP.ResultCodes.RS_4.NotFound,
-});
+```json
+{
+  "message": "Only %{available} left of %{variantId}.",
+  "statusCode": 409,
+  "normalized": {
+    "text": "Only %{available} left of %{variantId}.",
+    "code": "server.core.stock_reservation.reserve.unavailable",
+    "args": { "variantId": "V1", "available": 2 }
+  },
+  "extra": {
+    "details": { "locationId": "L9" }
+  },
+  "requestId": "abc-123-def",
+  "details": { "url": "http://localhost:3000/reservations", "path": "/reservations" }
+}
 ```
 
-## See Also
+`extra` is absent entirely when the throw site attached no context of its own.
 
-- [Controllers](/references/base/controllers) -- Throwing errors in route handlers
-- [Services](/references/base/services) -- Error handling in business logic
-- [Middlewares](/references/base/middlewares) -- The `appErrorHandler` middleware
-- [Helpers Index](/extensions/helpers/) -- All available helpers
-- [Logger Helper](/extensions/helpers/logger/) -- Logging errors
+> [!IMPORTANT]
+> **`messageCode` and `extra.messageArgs` are GONE from the response.** They duplicated `normalized.code` and `normalized.args`. Read `normalized` - it is the only source. A client still reading either must migrate: `translate(error.messageCode, error.extra?.messageArgs)` becomes `translate(error.normalized.code, error.normalized.args)`.
+>
+> Note the two `details`: the inner one is context the throw site attached (it went through `extra`), the outer one is the middleware's own request info. They are unrelated despite the name.
+
+> [!NOTE]
+> `message` and `normalized.text` are the same string unless a `transform` deliberately makes them differ - `message` stays the raw text the throw site wrote, `normalized.text` is what a client shows. Most errors never set `transform`, so most of the time they match.
+
+**Common status codes**
+
+| Scenario                 | Status | `HTTP.ResultCodes` path    |
+| ------------------------ | ------ | -------------------------- |
+| Invalid input            | 400    | `RS_4.BadRequest`          |
+| Missing/invalid auth     | 401    | `RS_4.Unauthorized`        |
+| Insufficient permissions | 403    | `RS_4.Forbidden`           |
+| Resource not found       | 404    | `RS_4.NotFound`            |
+| Duplicate resource       | 409    | `RS_4.Conflict`            |
+| Server failure           | 500    | `RS_5.InternalServerError` |
+
+## See also
+
+- [Controllers](/references/base/controllers) - throwing errors in route handlers
+- [Services](/references/base/services) - error handling in business logic
+- [Middlewares](/references/base/middlewares) - the `AppErrorMiddleware` handler
+- [Environment](/extensions/helpers/env/) - `Environment.DEVELOPMENT_ENVS`, the error-detail boundary
+- [Helpers Overview](/extensions/helpers/) - all available helpers
+
+**Files:**
+
+- [`packages/helpers/src/modules/error/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/error/index.ts) - module barrel
+- [`packages/helpers/src/modules/error/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/error/types.ts) - `ErrorSchema`, `TErrorResponse` (the RESPONSE schema, for OpenAPI)
+- [`packages/inversion/src/modules/error/app-error.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/error/app-error.ts) - `ApplicationError`, `getError`, `isApplicationError`
+- [`packages/inversion/src/modules/error/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/error/types.ts) - `TError`, `TErrorDefinition`, `TErrorNormalized`, `IErrorKeyRegistry`, `TRegisterErrors`
+- [`packages/inversion/src/modules/error/definition.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/error/definition.ts) - `ErrorScopes`, `TErrorScope`
+- [`packages/inversion/src/modules/error/message-code.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/error/message-code.ts) - `MessageCode`