# `error-codes.ts`

## Purpose

Hosts the canonical `HIBP_CODES` registry — exactly seven error codes that
classify every failure path inside `@suaveplan/hibp`. Lives at the package
root (rather than in a nested `errors/` directory) so the
`scripts/conformance.ts` scanner can find it and verify every code
is actually thrown by at least one production source file.

## Features

- Seven stable codes — `RATE_LIMITED`, `UNAUTHORIZED`, `NOT_FOUND`,
  `MALFORMED_RESPONSE`, `NETWORK_ERROR`, `ABORTED`, `PAYLOAD_TOO_LARGE`.
- Each value is the namespaced `HIBP.<KEY>` form, suitable for stable
  string matching in logs and structured-error registries.
- Registered through `defineCodes` from `@suaveplan/error` so the wider
  registry knows the namespace and can validate it at startup.

## Usage: Basic Example

```ts
import { HIBP_CODES, type HibpErrorCode } from "@suaveplan/hibp";

function isFatal(code: HibpErrorCode): boolean {
    return code === HIBP_CODES.MALFORMED_RESPONSE;
}
```

## Usage: Advanced Example

```ts
import { HibpError, HIBP_CODES } from "@suaveplan/hibp";

export function classifyHibpFailure(err: unknown): "retry" | "abort" | "report" {
    if (!(err instanceof HibpError)) return "report";
    switch (err.code) {
        case HIBP_CODES.RATE_LIMITED:
        case HIBP_CODES.NETWORK_ERROR:
            return "retry";
        case HIBP_CODES.ABORTED:
            return "abort";
        default:
            return "report";
    }
}
```

## API Reference

- `HIBP_CODES` — frozen record. Keys are bare names (`RATE_LIMITED`, …);
  values are namespaced strings (`"HIBP.RATE_LIMITED"`, …).
- `HibpErrorCode` — string-literal union of every registered value.

## Implementation Notes

The seven codes were chosen so each one corresponds to a distinct caller
remediation path: rate-limit backoff, credential rotation, resource
absence, schema regression, transport failure, user-driven cancellation,
and over-sized response. Adding a new code is a breaking change because
downstream consumers fan out on `code` literally. Removing a code is
likewise breaking and forbidden by the conformance gate, which verifies
every registered code is thrown by at least one production path.