Build Your Own Skills — Team Knowledge Capitalization

---
name: team-error-handling
description: Use when writing API handlers, service functions, or any code that might fail. Trigger when user asks to add error handling, create API endpoints, or handle async operations.
when_to_use: For all API routes, service layer functions, and async operations
author: SynapseGo Engineering Team
version: 1.0.0
---

# SynapseGo Error Handling Standard

Our codebase uses the Result pattern exclusively. Never throw errors in business logic.

## The Pattern

```typescript
// ✅ ALWAYS use Result type
type Result<T, E = AppError> = 
  | { ok: true; data: T }
  | { ok: false; error: E };

async function getUser(id: string): Promise<Result<User>> {
  try {
    const user = await db.user.findUnique({ where: { id } });
    if (!user) return { ok: false, error: new NotFoundError('User not found') };
    return { ok: true, data: user };
  } catch (e) {
    return { ok: false, error: new DatabaseError(e) };
  }
}
```

## Rules
- NEVER use `throw` in service/repository layer (only in middleware)
- ALWAYS check `result.ok` before using `result.data`
- AppError subclasses: NotFoundError, ValidationError, DatabaseError, AuthError
- Log errors at the boundary (API route level), not inside services

## API Route Pattern
```typescript
export async function GET(req: Request) {
  const result = await userService.getUser(req.params.id);
  if (!result.ok) return errorResponse(result.error); // centralized
  return Response.json(result.data);
}
```