Skip to main content
ZICQ

Skills ZICQ category:Design error-handling

Error Handling

Patterns for robust error handling across TypeScript, Python, and Go. Covers typed errors, error boundaries, retries, circuit breakers, and user-facing error messages. Use when designing error types, retries, circuit breakers, or user-facing failure messages in TypeScript, Python, or Go.

8695 installs

Official URL:skills.sh

What this skill does

Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.

What it does

Patterns for robust error handling across TypeScript, Python, and Go. Covers typed errors, error boundaries, retries, circuit breakers, and user-facing error messages

When to use it

designing error types, retries, circuit breakers, or user-facing failure messages in TypeScript, Python, or Go

How agents load it

Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: Error Handling Patterns; When to Activate; Core Principles; TypeScript / JavaScript; Typed Error Classes; Result Pattern (no-throw style).

File analysis

File analysis: instruction-only skill (SKILL.md). The agent loads the full body when activated.

Error Handling PatternsWhen to ActivateCore PrinciplesTypeScript / JavaScriptTyped Error ClassesResult Pattern (no-throw style)API Error Handler (Next.js / Express)React Error BoundaryPythonCustom Exception HierarchyFastAPI Global Exception HandlerGo

Source category:skills.sh agent-skill

SKILL.md & Agent activation

Official spec ↗
name
error-handling
description
Patterns for robust error handling across TypeScript, Python, and Go. Covers typed errors, error boundaries, retries, circuit breakers, and user-facing error messages. Use when designing error types, retries, circuit breakers, or user-facing failure messages in TypeScript, Python, or Go.
  1. DiscoverThe client exposes names and descriptions to the agent.
  2. ActivateYour request or the task context selects the skill and loads its instructions.
  3. Load resourcesReferenced scripts, documentation and assets are used when needed.

Invocation syntax and available tools depend on your Agent client. Client integration guide ↗

Install this skill

Skills CLI ↗

Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.

Ask your Agent to install

Copy these instructions to a compatible agent and confirm the target directory matches your client.

Install the agent skill "error-handling" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-c63e5c450e2ee8eb-Error-Handling.html
Save it as .cursor/skills/error-handling/SKILL.md or .claude/skills/error-handling/SKILL.md and keep the frontmatter name and description exactly as-is.

Full package on GitHub ↗

Install from the terminal · Skills CLI

Requires Node.js and npx. First inspect the repository's skill list to confirm the name.

npx skills add 'https://github.com/affaan-m/ecc' --list

npx skills add 'https://github.com/affaan-m/ecc' --skill 'error-handling'

The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.

Readable layout
--- name: error-handling description: Patterns for robust error handling across TypeScript, Python, and Go. Covers typed errors, error boundaries, retries, circuit breakers, and user-facing error messages. Use when designing error types, retries, circuit breakers, or user-facing failure messages in TypeScript, Python, or Go. metadata: origin: ECC --- # Error Handling Patterns Consistent, robust error handling patterns for production applications. ## When to Activate - Designing error types or exception hierarchies for a new module or service - Adding retry logic or circuit breakers for unreliable external dependencies - Reviewing API endpoints for missing error handling - Implementing user-facing error messages and feedback - Debugging cascading failures or silent error swallowing ## Core Principles 1. **Fail fast and loudly** — surface errors at the boundary where they occur; don't bury them 2. **Typed errors over string messages** — errors are first-class values with structure 3. **User messages ≠ developer messages** — show friendly text to users, log full context server-side 4. **Never swallow errors silently** — every `catch` block must either handle, re-throw, or log 5. **Errors are part of your API contract** — document every error code a client may receive ## TypeScript / JavaScript ### Typed Error Classes ```typescript // Define an error hierarchy for your domain export class AppError extends Error { constructor( message: string, public readonly code: string, public readonly statusCode: number = 500, public readonly details?: unknown, ) { super(message) this.name = this.constructor.name // Maintain correct prototype chain in transpiled ES5 JavaScript. // Required for `instanceof` checks (e.g., `error instanceof NotFoundError`) // to work correctly when extending the built-in Error class. Object.setPrototypeOf(this, new.target.prototype) } } export class NotFoundError extends AppError { constructor(resource: string, id: string) { super(`${resource} not found: ${id}`, 'NOT_FOUND', 404) } } export class ValidationError extends AppError { constructor(message: string, details: { field: string; message: string }[]) { super(message, 'VALIDATION_ERROR', 422, details) } } export class UnauthorizedError extends AppError { constructor(reason = 'Authentication required') { super(reason, 'UNAUTHORIZED', 401) } } export class RateLimitError extends AppError { constructor(public readonly retryAfterMs: number) { super('Rate limit exceeded', 'RATE_LIMITED', 429) } } ``` ### Result Pattern (no-throw style) For operations where failure is expected and common (parsing, external calls): ```typescript type Result = | { ok: true; value: T } | { ok: false; error: E } function ok(value: T): Result { return { ok: true, value } } function err(error: E): Result { return { ok: false, error } } // Usage async function fetchUser(id: string): Promise> { try { const user = await db.users.findUnique({ where: { id } }) if (!user) return err(new NotFoundError('User', id)) return ok(user) } catch (e) { return err(new AppError('Database error', 'DB_ERROR')) } } const result = await fetchUser('abc-123') if (!result.ok) { // TypeScript knows result.error here logger.error('Failed to fetch user', { error: result.error }) return } // TypeScript knows result.value here console.log(result.value.email) ``` ### API Error Handler (Next.js / Express) ```typescript import { NextRequest, NextResponse } from 'next/server' function handleApiError(error: unknown): NextResponse { // Known application error if (error instanceof AppError) { return NextResponse.json( { error: { code: error.code, message: error.message, ...(error.details ? { details: error.details } : {}), }, }, { status: error.statusCode }, ) } // Zod validation error if (error instanceof z.ZodError) { return NextResponse.json( { error: { code: 'VALIDATION_ERROR', message: 'Request validation failed', details: error.issues.map(i => ({ field: i.path.join('.'), message: i.message, })), }, }, { status: 422 }, ) } // Unexpected error — log details, return generic message console.error('Unexpected error:', error) return NextResponse.json( { error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' } }, { status: 500 }, ) } export async function POST(req: NextRequest) { try { // ... handler logic } catch (error) { return handleApiError(error) } } ``` ### React Error Boundary ```typescript import { Component, ErrorInfo, ReactNode } from 'react' interface Props { fallback: ReactNode onError?: (error: Error, info: ErrorInfo) => void children: ReactNode } interface State { hasError: boolean error: Error | null } export class ErrorBoundary extends Component { state: State = { hasError: false, error: null } static getDerivedStateFromError(error: Error): State { return { hasError: true, error } } componentDidCatch(error: Error, info: ErrorInfo) { this.props.onError?.(error, info) console.error('Unhandled React error:', error, info) } render() { if (this.state.hasError) return this.props.fallback return this.props.children } } // Usage Something went wrong. Please refresh.

}> ``` ## Python ### Custom Exception Hierarchy ```python class AppError(Exception): """Base application error.""" def __init__(self, message: str, code: str, status_code: int = 500): super().__init__(message) self.code = code self.status_code = status_code class NotFoundError(AppError): def __init__(self, resource: str, id: str): super().__init__(f"{resource} not found: {id}", "NOT_FOUND", 404) class ValidationError(AppError): def __init__(self, message: str, details: list[dict] | None = None): super().__init__(message, "VALIDATION_ERROR", 422) self.details = details or [] ``` ### FastAPI Global Exception Handler ```python from fastapi import FastAPI, Request from fastapi.responses import JSONResponse app = FastAPI() @app.exception_handler(AppError) async def app_error_handler(request: Request, exc: AppError) -> JSONResponse: return JSONResponse( status_code=exc.status_code, content={"error": {"code": exc.code, "message": str(exc)}}, ) @app.exception_handler(Exception) async def generic_error_handler(request: Request, exc: Exception) -> JSONResponse: # Log full details, return generic message logger.exception("Unexpected error", exc_info=exc) return JSONResponse( status_code=500, content={"error": {"code": "INTERNAL_ERROR", "message": "An unexpected error occurred"}}, ) ``` ## Go ### Sentinel Errors and Error Wrapping ```go package domain import "errors" // Sentinel errors for type-checking var ( ErrNotFound = errors.New("not found") ErrUnauthorized = errors.New("unauthorized") ErrConflict = errors.New("conflict") ) // Wrap errors with context — never lose the original func (r *UserRepository) FindByID(ctx context.Context, id string) (*User, error) { user, err := r.db.QueryRow(ctx, "SELECT * FROM users WHERE id = $1", id) if errors.Is(err, sql.ErrNoRows) { return nil, fmt.Errorf("user %s: %w", id, ErrNotFound) } if err != nil { return nil, fmt.Errorf("querying user %s: %w", id, err) } return user, nil } // At the handler level, unwrap to determine response func (h *Handler) GetUser(w http.ResponseWriter, r *http.Request) { user, err := h.service.GetUser(r.Context(), chi.URLParam(r, "id")) if err != nil { switch { case errors.Is(err, domain.ErrNotFound): writeError(w, http.StatusNotFound, "not_found", err.Error()) case errors.Is(err, domain.ErrUnauthorized): writeError(w, http.StatusForbidden, "forbidden", "Access denied") default: slog.Error("unexpected error", "err", err) writeError(w, http.StatusInternalServerError, "internal_error", "An unexpected error occurred") } return } writeJSON(w, http.StatusOK, user) } ``` ## Retry with Exponential Backoff ```typescript interface RetryOptions { maxAttempts?: number baseDelayMs?: number maxDelayMs?: number retryIf?: (error: unknown) => boolean } async function withRetry( fn: () => Promise, options: RetryOptions = {}, ): Promise { const { maxAttempts = 3, baseDelayMs = 500, maxDelayMs = 10_000, retryIf = () => true, } = options let lastError: unknown for (let attempt = 1; attempt <= maxAttempts; attempt++) { try { return await fn() } catch (error) { lastError = error if (attempt === maxAttempts || !retryIf(error)) throw error const jitter = Math.random() * baseDelayMs const delay = Math.min(baseDelayMs * 2 ** (attempt - 1) + jitter, maxDelayMs) await new Promise(resolve => setTimeout(resolve, delay)) } } throw lastError } // Usage: retry transient network errors, not 4xx const data = await withRetry(() => fetch('/api/data').then(r => r.json()), { maxAttempts: 3, retryIf: (error) => !(error instanceof AppError && error.statusCode < 500), }) ``` ## User-Facing Error Messages Map error codes to human-readable messages. Keep technical details out of user-visible text. ```typescript const USER_ERROR_MESSAGES: Record = { NOT_FOUND: 'The requested item could not be found.', UNAUTHORIZED: 'Please sign in to continue.', FORBIDDEN: "You don't have permission to do that.", VALIDATION_ERROR: 'Please check your input and try again.', RATE_LIMITED: 'Too many requests. Please wait a moment and try again.', INTERNAL_ERROR: 'Something went wrong on our end. Please try again later.', } export function getUserMessage(code: string): string { return USER_ERROR_MESSAGES[code] ?? USER_ERROR_MESSAGES.INTERNAL_ERROR } ``` ## Error Handling Checklist Before merging any code that touches error handling: - [ ] Every `catch` block handles, re-throws, or logs — no silent swallowing - [ ] API errors follow the standard envelope `{ error: { code, message } }` - [ ] User-facing messages contain no stack traces or internal details - [ ] Full error context is logged server-side - [ ] Custom error classes extend a base `AppError` with a `code` field - [ ] Async functions surface errors to callers — no fire-and-forget without fallback - [ ] Retry logic only retries retriable errors (not 4xx client errors) - [ ] React components are wrapped in `ErrorBoundary` for rendering errors

Related skills

Design

Automation Workflows

Design and implement automation workflows to save time and scale operations as a solopreneur. Use when identifying repetitive tasks to autom…

Design

Ui Ux Pro Max

UI/UX design intelligence and implementation guidance for building polished interfaces. Use when the user asks for UI design, UX flows, info…

Design

Frontend Design

Expert frontend design guidelines for creating beautiful, modern UIs. Use when building landing pages, dashboards, or any user interface.

Design

N8n Workflow Automation

Designs and outputs n8n workflow JSON with robust triggers, idempotency, error handling, logging, retries, and human-in-the-loop review queu…