error-cause-code

Extract a single error code from an error and its cause chain — for alerting, filtering, grouping and logging. Finds the root cause hidden inside wrapped errors, such as a PostgreSQL SQLSTATE ("08006", "23505") inside a Drizzle ORM "Failed query" error, or an HTTP status code (404, 429) from an API client error. Zero dependencies, TypeScript, ESM, and runtime-agnostic (Node.js, Cloudflare Workers / edge, browsers).

Why

Many libraries wrap the real error: Drizzle ORM throws "Failed query" and puts the actual postgres error in cause. To classify an error you have to walk the whole nested error chain. findErrorCode does that and returns one flat string | null, wherever the code came from — err.code or err.status, at any depth.

Use cases

• Database alerts: pull the Postgres SQLSTATE out of a Drizzle error and alert only on connection failures ("08006"), not on unique violations ("23505").
• Error monitoring / grouping: use the code as a fingerprint in Sentry or similar, so every error doesn't collapse into one "Failed query" group.
• HTTP error filtering: read the status from an HTTP error — ignore 404, retry 429.
• Structured logging: add one flat errorCode field to logs for search and aggregation.

Install

npm install error-cause-code

Usage

import { findErrorCode } from "error-cause-code";

// top-level code
findErrorCode(Object.assign(new Error("dup"), { code: "23505" })); // "23505"

// falls back to http status when there is no code
findErrorCode(Object.assign(new Error("nf"), { status: 404 })); // "404"

// walks down the cause chain
const pg = Object.assign(new Error("closed"), { code: "08006" });
const dz = Object.assign(new Error("Failed query"), { cause: pg });
findErrorCode(dz); // "08006"

// null when no code is found
findErrorCode(new Error("plain")); // null

API

findErrorCode(err: unknown): string | null

At each level of the chain, checks in this order:

Order	Condition
err.code	string or number → String(code)
err.status	number → String(status)
err.cause	recurse (max depth 5)

Returns null if no code is found. Never throws, even past the depth limit or on non-object input.

License

MIT