# error-codes/error-codes

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Defines the stable error-code registry for `@suaveplan/api-plugin-audit` and the concrete `AuditPluginError` class used by every production code path. The registry is shared with `@suaveplan/error`'s singleton via `defineCodes("AUDIT_PLUGIN", [...])`, so every code surfaces in the unified `ErrorCodes` table consumed by logging, metrics, and translation layers.

Every code documented here corresponds to a real failure mode the plugin can surface at the call site. Consumers branch on the string code (`error.code === AUDIT_PLUGIN_CODES.INVALID_INPUT`) rather than `instanceof` checks against private subclasses.

## Features

- Four stable codes: `INVALID_INPUT`, `SERVICE_NOT_AVAILABLE`, `SINK_INIT_FAILED`, `SINK_WRITE_FAILED`.
- `AuditPluginError` carries `cause`, `context`, and the `code` discriminant via the `SuaveplanError` base.
- Every code is raised by at least one production code path and pinned by `src/api-plugin-audit.spec-conformance.test.ts`.

## Usage: Basic

```ts
import {
    AUDIT_PLUGIN_CODES,
    AuditPluginError,
} from "@suaveplan/api-plugin-audit/error-codes/error-codes";

throw new AuditPluginError(
    AUDIT_PLUGIN_CODES.SERVICE_NOT_AVAILABLE,
    "audit plugin requires the `app` service in ServiceRegistry",
    { context: { missing: ["app"], statusCode: 500 } }
);
```

## Usage: Advanced

```ts
import {
    AUDIT_PLUGIN_CODES,
    AuditPluginError,
} from "@suaveplan/api-plugin-audit/error-codes/error-codes";

try {
    await sink.save(event);
} catch (cause) {
    const err = new AuditPluginError(
        AUDIT_PLUGIN_CODES.SINK_WRITE_FAILED,
        "audit sink rejected save()",
        { cause, context: { eventId: event.id } }
    );
    logger.warn(err.message, { code: err.code, cause: err.cause });
}
```

## API Reference

- `AUDIT_PLUGIN_CODES` — frozen record from `defineCodes("AUDIT_PLUGIN", [...])`.
- `AuditPluginErrorCode` — string-literal union of the registered codes.
- `class AuditPluginError extends SuaveplanError<AuditPluginErrorCode>` — public constructor accepts `(code, message, options?)`.

## Implementation Notes

The registry is small on purpose. Validation failures map to `INVALID_INPUT`; structural prerequisite failures map to `SERVICE_NOT_AVAILABLE`; sink construction failures map to `SINK_INIT_FAILED`; per-request sink rejections map to `SINK_WRITE_FAILED`. The middleware path never re-throws `SINK_WRITE_FAILED` — it logs and counts so the request response is unaffected (telemetry must not 500 the caller).