error-handling-patterns

Error Handling Patterns

Error Classification

Type	Cause	Can Recover?	Example
Operational	Runtime problem in a correctly-written program	Yes	Network timeout, disk full, invalid input
Programmer	Bug in the code	No	TypeError, null dereference, assertion failure

Operational errors: Anticipate them, handle explicitly, retry if transient, return clear error to caller, log with context. Programmer errors: Crash immediately (fail fast), fix the bug, log full stack trace.

Try/Catch Patterns

When to Catch

• You can meaningfully recover (retry, fallback, return default)
• You need to translate the error for the caller
• You are at a boundary (HTTP handler, event listener, queue consumer)
• You need to add context before re-throwing

When to Propagate

• You cannot recover; let the caller decide
• The error is already descriptive enough
• You are in a pure business logic layer (no I/O awareness)

Catch, Add Context, Re-throw

async function getUser(id: string): Promise<User> {
  try {
    return await db.query("SELECT * FROM users WHERE id = $1", [id]);
  } catch (error) {
    throw new DatabaseError(`Failed to fetch user ${id}`, { cause: error });
  }
}

def get_user(user_id: str) -> User:
    try:
        return db.query("SELECT * FROM users WHERE id = %s", (user_id,))
    except DatabaseError as e:
        raise UserFetchError(f"Failed to fetch user {user_id}") from e

Catch at Boundaries

app.get("/users/:id", async (req, res) => {
  try {
    const user = await getUser(req.params.id);
    res.json(user);
  } catch (error) {
    if (error instanceof NotFoundError) {
      return res.status(404).json({ error: { code: "RESOURCE_NOT_FOUND", message: "User not found." } });
    }
    logger.error("Unhandled error in GET /users/:id", { error, requestId: req.id });
    res.status(500).json({ error: { code: "INTERNAL_ERROR", message: "An unexpected error occurred." } });
  }
});