Skip to content

MustafaKucukcoskun/Refine-agent-kit / .agents/skills/error-handling-patterns

error-handling-patterns

Verified

Error Handling Patterns

Errors are not failures — they are information. The question is whether your system knows what to do with them.

When to Use vs. Related Skills

You want to…Use
General error strategyerror-handling-patterns (this)
Async-specific errorsasync-javascript-patterns + this
Debug why something failedsystematic-debugging
Logging / metrics / tracesobservability-patterns + this
API error response shapeapi-patterns + this

1. Error Type Hierarchy

Design a typed hierarchy. Never use bare Error.

// TypeScript
export class AppError extends Error {
  constructor(
    public readonly code: string,
    message: string,
    public readonly cause?: unknown,
    public readonly meta?: Record<string, unknown>,
  ) {
    super(message);
    this.name = this.constructor.name;
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super("NOT_FOUND", `${resource} ${id} not found`);
  }
}

export class ValidationError extends AppError {
  constructor(field: string, reason: string) {
    super("VALIDATION", `${field}: ${reason}`);
  }
}

export class ExternalServiceError extends AppError {
  constructor(service: string, cause?: unknown) {
    super("EXTERNAL_SERVICE", `${service} unavailable`, cause);
  }
}

Same pattern in Python:

class AppError(Exception):
    code: str = "APP_ERROR"
    def __init__(self, message: str, *, cause: Exception | None = None, **meta):
        super().__init__(message)
        self.cause = cause
        self.meta = meta

class NotFoundError(AppError):
    code = "NOT_FOUND"

class ValidationError(AppError):
    code = "VALIDATION"

2. Error Classification — 4 Categories

CategoryExamplesAction
Programmer errorundefined is not a function, type mismatchCrash, page the dev
User errorInvalid input, missing authReturn 4xx, clear message
Expected operationalTimeout, rate-limited, 503 from depRetry with backoff
Unexpected operationalDB connection lost, disk fullAlert, degrade gracefully

Don't handle categories the same way. Crashing on programmer errors is CORRECT.


3. Retry with Exponential Backoff + Jitter

export async function retry<T>(
  fn: () => Promise<T>,
  {
    maxAttempts = 3,
    baseMs = 200,
    maxMs = 5000,
    shouldRetry = (e: unknown) => isTransient(e),
  } = {},
): Promise<T> {
  let lastErr: unknown;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (e) {
      lastErr = e;
      if (!shouldRetry(e) || attempt === maxAttempts) break;
      const ms = Math.min(baseMs * 2 ** (attempt - 1), maxMs);
      const jittered = ms * (0.5 + Math.random() * 0.5);
      await new Promise((r) => setTimeout(r, jittered));
    }
  }
  throw lastErr;
}

function isTransient(e: unknown): boolean {
  if (e instanceof ExternalServiceError) return true;
  if (e instanceof Error && "code" in e) {
    return ["ECONNRESET", "ETIMEDOUT", "ECONNREFUSED"].includes(e.code as string);
  }
  return false;
}

Key rules:

  • Always add jitter — prevents synchronized retry storms
  • Never retry user errors (wastes cycles, confuses user)
  • Cap max attempts AND max total time

4. Circuit Breaker

Stop hammering a dead service. Three states: CLOSED (normal) → OPEN (rejecting) → HALF_OPEN (testing recovery).

export class CircuitBreaker {
  private failures = 0;
  private state: "CLOSED" | "OPEN" | "HALF_OPEN" = "CLOSED";
  private openedAt = 0;

  constructor(
    private readonly threshold = 5,
    private readonly resetMs = 30_000,
  ) {}

  async exec<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === "OPEN") {
      if (Date.now() - this.openedAt > this.resetMs) {
        this.state = "HALF_OPEN";
      } else {
        throw new ExternalServiceError("circuit open");
      }
    }
    try {
      const result = await fn();
      if (this.state === "HALF_OPEN") {
        this.state = "CLOSED";
        this.failures = 0;
      }
      return result;
    } catch (e) {
      this.failures++;
      if (this.failures >= this.threshold) {
        this.state = "OPEN";
        this.openedAt = Date.now();
      }
      throw e;
    }
  }
}

Libraries: opossum (Node), pybreaker (Python).


5. Graceful Degradation

When a non-critical dep fails, don't 500 the whole response. Return partial with a flag.

async function getPageData(userId: string) {
  const [profile, recommendations] = await Promise.allSettled([
    getProfile(userId),       // critical
    getRecommendations(userId), // nice-to-have
  ]);

  if (profile.status === "rejected") throw profile.reason;

  return {
    profile: profile.value,
    recommendations: recommendations.status === "fulfilled"
      ? recommendations.value
      : [],
    recommendationsAvailable: recommendations.status === "fulfilled",
  };
}

6. Frontend Error Boundaries (React)

class ErrorBoundary extends React.Component<
  { fallback: React.ReactNode; children: React.ReactNode },
  { hasError: boolean }
> {
  state = { hasError: false };
  static getDerivedStateFromError() { return { hasError: true }; }
  componentDidCatch(error: Error, info: React.ErrorInfo) {
    logger.error({ error, info }, "boundary caught");
  }
  render() {
    return this.state.hasError ? this.props.fallback : this.props.children;
  }
}

// Wrap critical sections, not the whole app
<ErrorBoundary fallback={<InlineError />}>
  <Analytics />
</ErrorBoundary>

7. Structured HTTP Error Responses

{
  "code": "VALIDATION",
  "message": "email: must be a valid email",
  "details": {
    "field": "email",
    "value": "not-an-email"
  },
  "requestId": "req_abc123"
}

Rules:

  • Always include code (machine-readable) and message (human-readable)
  • Include requestId for support traceability
  • Never leak stack traces in production responses
  • Use problem+json (RFC 7807) for public APIs

8. Timeout Strategies

Every I/O call needs a timeout. No exceptions.

// Always cap HTTP calls
const res = await fetch(url, {
  signal: AbortSignal.timeout(5000),
});

// DB pool timeout
const pool = new Pool({ connectionTimeoutMillis: 3000, idleTimeoutMillis: 10000 });

// Per-request server timeout (prevent hung workers)
app.use(timeout("30s"));

Budget rule: user request budget = sum of downstream timeouts + processing time.


9. Logging vs. Rethrowing

Two mistakes to avoid:

Mistake 1: Log-and-swallow

// ❌ caller thinks it worked
try { await save(); } catch (e) { logger.error({ e }); }

Mistake 2: Log at every level

// ❌ same error logged 5 times
try { ... } catch (e) { logger.error({ e }); throw e; }

Right: log once at the boundary (HTTP handler, job runner)

// At the outermost handler
app.use((err, req, res, next) => {
  logger.error({ err, requestId: req.id }, "request failed");
  res.status(500).json({ code: "INTERNAL", requestId: req.id });
});

// Inside business logic: just throw
async function save(data) {
  const result = await db.save(data);
  if (!result) throw new AppError("SAVE_FAILED", "could not save");
  return result;
}

10. Rollback / Compensating Actions

For multi-step operations:

async function createUserWithStripe(data: UserData) {
  const customer = await stripe.customers.create({ email: data.email });
  try {
    return await db.user.create({ data: { ...data, stripeId: customer.id } });
  } catch (e) {
    // Compensating action — undo the Stripe customer
    await stripe.customers.del(customer.id).catch(() => {}); // best-effort
    throw e;
  }
}

For DB multi-step: use transactions. For distributed: saga pattern.


Anti-Patterns

Anti-patternWhy badFix
Empty catch blockSilent failureHandle OR propagate with context
Catching Error catch-all at top of functionHides programmer errorsCatch specific subclasses
Error message = "Something went wrong"UnactionableInclude what/where/why
Retry on 4xxWaste; never succeedsOnly retry 5xx and timeouts
No timeout on HTTP callHangs foreverAlways pass AbortSignal/timeout
Throwing strings (throw "bad")No stack, no typeAlways throw Error subclasses
Error response leaks stack traceSecurity riskStrip in prod; use requestId
Rethrow loses causeDebugging hardernew Error("...", { cause: e })

Pre-Ship Checklist

  • Typed error hierarchy exists
  • Every I/O has timeout
  • Retries only on transient errors, with jitter
  • Circuit breaker around unreliable deps
  • Graceful degradation for non-critical deps
  • Error responses follow problem+json or documented shape
  • Error logged once (at the boundary), not at every level
  • Multi-step operations have rollback/compensation
  • Stack traces not exposed in production responses

Related Skills

  • async-javascript-patterns — async-specific error propagation
  • observability-patterns — error rate metrics, structured logs
  • systematic-debugging — when errors don't match symptoms
  • testing-patterns — testing the error paths
  • api-patterns — HTTP error response design
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall