Numeric → semantic error codes

What changed

Before this ship, HM-AUTH-001 meant “Unauthorized” on one route, “Sign-in required” on another, “User not found” on a third, and “Invalid email or password” in the registry. Same code, four different conditions. An SDK consumer trying to handle the error class couldn't pin reliably — they had to parse the message string, which is brittle (the messages are user-facing English and may be localized in the future).

Each numeric was split into 1–3 specific semantic codes that name the actual condition. The code is the documentation now: HM-AUTH-MISSING tells you exactly what to fix without parsing English.

Format

HM-{DOMAIN}-{CONDITION}

Examples:
  HM-AUTH-MISSING
  HM-AUTH-INVALID_KEY
  HM-VALIDATION-FAILED
  HM-RATELIMIT-EXCEEDED
  HM-THREAD-NOT_FOUND

Domain is the resource or concern (AUTH, TENANT, THREAD, AI, WEBHOOK, etc.). Condition is SCREAMING_SNAKE_CASE describing what failed. The pair is unique. No version is encoded — codes are stable contracts.

Migration steps

1. 1

   Search your codebase for legacy numeric codes.

   Grep for HM-[A-Z]+-\d+ across your project. Common matches: error-handling middleware, alert rules, dashboard filters, retry-classification helpers.

2. 2

   For each match, find its semantic equivalent.

   Use the mapping table below. Where one numeric maps to several semantics, the call-site context tells you which one — e.g. on a sign-in route, HM-AUTH-001 almost always meant HM-AUTH-INVALID_CREDENTIALS; on a protected API route it meant HM-AUTH-MISSING.

3. 3

   If you cannot enumerate all sites cleanly, use a translation map.

   Wrap your error-handling at one place with a function that translates legacy codes to semantics for backwards-compat downstream consumers (alerts, dashboards). Example below.

4. 4

   Verify with a smoke test.

   Trigger a known auth failure (e.g. omit the Authorization header) and confirm the returned err.code is HM-AUTH-MISSING, not HM-AUTH-001.

Before / after — Node.js

try {
  await client.threads.list();
} catch (err) {
  if (err.code === 'HM-AUTH-001') {
    // Was: catch all auth failures.
    // After upgrade: NEVER fires — code is now HM-AUTH-MISSING / HM-AUTH-INVALID_KEY.
    refreshApiKey();
  }
}

try {
  await client.threads.list();
} catch (err) {
  // Domain prefix matches every auth-related code.
  if (err.code?.startsWith('HM-AUTH-')) {
    refreshApiKey();
  }

  // Or, narrower handlers when the recovery differs:
  if (err.code === 'HM-AUTH-INVALID_KEY') {
    promptUserToGenerateNewKey();
  }
  if (err.code === 'HM-RATELIMIT-EXCEEDED') {
    backoffAndRetry(err.headers['retry-after']);
  }
}

Before / after — Python

try:
    threads = client.threads.list()
except HelpMeshError as err:
    if err.code == "HM-AUTH-001":
        refresh_api_key()

try:
    threads = client.threads.list()
except HelpMeshError as err:
    if err.code.startswith("HM-AUTH-"):
        refresh_api_key()
    elif err.code == "HM-RATELIMIT-EXCEEDED":
        retry_after = err.headers.get("retry-after", 1)
        time.sleep(int(retry_after))

Translation map strategy (LEGACY_CODE_ALIASES)

The HelpMesh source ships a LEGACY_CODE_ALIASES reverse-lookup map you can mirror in your own code. It maps every retired numeric code to its modern semantic(s). If your error-handling has many call sites and refactoring them all in one PR is risky, wrap responses at the boundary instead and translate downstream:

// Wrap your existing alerting/dashboard code so old rules keep firing
// during the transition window. Remove this shim once all consumers
// are updated to recognize semantic codes directly.

const SEMANTIC_TO_LEGACY: Record<string, string> = {
  'HM-AUTH-MISSING':         'HM-AUTH-001',
  'HM-AUTH-INVALID_KEY':     'HM-AUTH-001',
  'HM-AUTH-INVALID_CREDENTIALS': 'HM-AUTH-001',
  'HM-AUTH-USER_NOT_FOUND':  'HM-AUTH-001',
  'HM-RATELIMIT-EXCEEDED':   'HM-RATE-001',
  // ...full map mirrors LEGACY_CODE_ALIASES from packages/core/src/errors/registry.ts
};

function classifyError(err: { code: string }) {
  // New code paths see semantics:
  newAlertingPath(err.code);

  // Legacy dashboards keep working:
  const legacy = SEMANTIC_TO_LEGACY[err.code];
  if (legacy) legacyAlertingPath(legacy);
}

Mapping table — retired numeric codes

The 10 highest-frequency numerics. The full 44-entry map ships with the source at packages/core/src/errors/registry.ts.

All semantic codes in one place

The complete public-facing error registry (39 codes shown — the registry has 47 entries; the remainder are internal-only).