designing-errors

Subclass Error, set this.name to the class name in the constructor, and declare readonly code as a literal type rather than string. Keep the underlying failure on the cause property instead of folding it into the message.

Use an ERR_ prefix with SCREAMING_SNAKE_CASE describing the failure, not the function that raised it, such as ERR_LLM_TIMEOUT. Under src/** the prefix names the owning layer; under scripts/** it names the check's stage, like ERR_AGENTS_*.

Callers should branch on code or use instanceof on the class, never on message text. The code is a stable string literal contract, while message is prose for humans that may be reworded at any time.

An error must never carry credentials, API keys, prompts, model outputs, or parsed request bodies, because errors travel into logs, aggregators, and response bodies. Name the shape instead, such as a field path or an exceeded length.

Return the caller's reason as the same object rather than wrapping it in a fresh error, so error.cause === myReason identity checks still pass. Helpers like asError and abortedLlmError keep the raw reason on cause.

Use a discriminated union keyed on code, or one class per failure, when a function can fail for several structurally different reasons. This lets consumers switch on code and get every field narrowed instead of checking optional fields.