skills/docs/api-stack/api/api-plugin-user/src/error-codes/error-codes.md

error-codes/error-codes

(no submodules)

Purpose

The error-codes module defines the stable registry of programmatic failure codes raised by @suaveplan/api-plugin-user. Every code lives behind a UserError class extending the canonical SuaveplanError base, so callers can instanceof UserError to narrow error.code to the union of seven USER.* codes — never a free-form string. The registry is the contract: adding, removing, or renaming a code is a breaking change for consumers asserting on the value.

Features

• Seven stable codes covering every plugin failure path: lookup misses, invalid factory options, disabled self-delete, profile-update failures, missing services, schema-apply failures, and route-prefix collisions.
• defineCodes("USER", [...]) registers the codes globally so the unified error registry can resolve them by string.
• UserError carries userCode alongside the canonical code field so downstream code that does not import the base class can still branch on the discriminant.
• Each thrown instance carries context.statusCode so the host's error-handler middleware maps the failure to the right HTTP status without per-route boilerplate.

Usage: Basic

import { USER_CODES, UserError } from "@suaveplan/api-plugin-user/error-codes/error-codes";

if (!row) {
    throw new UserError(USER_CODES.NOT_FOUND, "user not found", {
        context: { statusCode: 404, userId: id },
    });
}

Usage: Advanced

Compose the registry with the @suaveplan/error cause chain so the original database error survives translation to HTTP without losing its stack:

try {
    await db.execute(sql);
} catch (cause) {
    throw new UserError(USER_CODES.PROFILE_UPDATE_FAILED, "patch failed", {
        cause,
        context: { statusCode: 500, userId, fields: Object.keys(patch) },
    });
}

API Reference

USER_CODES

Readonly<Record<"NOT_FOUND" | "INVALID_INPUT" | "SELF_DELETE_DISABLED" | "PROFILE_UPDATE_FAILED" | "SERVICE_NOT_AVAILABLE" | "SCHEMA_APPLY_FAILED" | "ROUTE_PREFIX_COLLISION", string>>. Each value is the fully-qualified "USER.<NAME>" string used as the discriminant.

UserError

class UserError extends SuaveplanError<UserErrorCode> — public constructor (code, message, options?) so callers can construct the error directly. userCode mirrors code for ergonomic narrowing.

UserErrorCode

Union of all seven literal code values.

Implementation Notes

• defineCodes performs duplicate-detection at module-load time; a duplicate name throws synchronously so a stale build fails loudly.
• The seven codes are intentionally cohesive — admin-side listings, avatar uploads, and GDPR export are scoped to follow-up plugins with their own registries.
• statusCode is always carried on context, not as a top-level field, so the error registry remains transport-agnostic.