error-handling - SKILL.md Agent Skill

name: error-handling description: | Use when throwing, catching, wrapping, documenting, or testing runtime errors in aa-sdk packages. last_verified: 2026-05-06

Runtime package errors should use the SDK error hierarchy rooted at @alchemy/common BaseError.

Rule	When to read
BaseError	Before adding package runtime errors.
No plain Error	Before writing throw statements in `packages/`.
Raise footgun	Before using or modifying `raise`.

packages/common/src/errors/BaseError.ts extends viem's BaseError.
.eslintrc forbids throw new Error(...) in packages/**/* except tests.
.eslintrc forbids import { BaseError } from "viem" to prevent accidentally using viem's BaseError instead of @alchemy/common's.
packages/wallet-apis/src/utils/schema.ts wraps Zod validation failures in @alchemy/common BaseError.