playbooks

home / skills / tlabs-xyz / tbtc-v2-performance / global-error-handling

global-error-handling skill

/.claude/skills/global-error-handling

This skill guides you to implement robust error handling across code, API boundaries, and user-facing messages with fail-fast and graceful degradation.

npx playbooks add skill tlabs-xyz/tbtc-v2-performance --skill global-error-handling

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.1 KB
---
name: Global Error Handling
description: Implement robust error handling with user-friendly messages, specific exception types, fail-fast validation, centralized error boundaries, and graceful degradation. Use this skill when implementing try-catch blocks, throwing or catching exceptions, creating custom error classes or types, implementing error boundaries or middleware, validating input and checking preconditions, implementing retry logic with exponential backoff, handling external service failures, cleaning up resources in finally blocks, creating user-facing error messages, implementing centralized error handling at API boundaries, or designing systems for graceful degradation. Use across all programming languages when implementing error handling logic in any code file.
---

## When to use this skill

- When implementing try-catch blocks or error handling logic
- When throwing or catching exceptions or errors
- When creating custom error classes, types, or error hierarchies
- When implementing error boundaries, middleware, or centralized error handlers
- When validating input and checking preconditions (fail-fast approach)
- When implementing retry logic with exponential backoff for external services
- When handling failures from external APIs, databases, or third-party services
- When cleaning up resources (file handles, connections, locks) in finally blocks or equivalent
- When creating user-facing error messages that are clear and actionable
- When implementing error handling at API boundaries or controller layers
- When designing systems for graceful degradation when non-critical services fail
- When preventing exposure of technical details or security information in errors
- When working with error handling in any programming language or framework

# Global Error Handling

This Skill provides Claude Code with specific guidance on how to adhere to coding standards as they relate to how it should handle global error handling.

## Instructions

For details, refer to the information provided in this file:
[global error handling](../../../agent-os/standards/global/error-handling.md)

Overview

This skill teaches how to implement robust, centralized error handling across services and codebases. It focuses on user-friendly messages, specific exception types, fail-fast validation, centralized boundaries, and graceful degradation to keep systems reliable and secure. Use it to standardize try/catch patterns, custom errors, and recovery strategies across languages and frameworks.

How this skill works

The skill inspects places where errors can originate (input validation, external calls, resource management) and recommends concrete patterns: fail-fast checks, meaningful custom error classes, centralized handlers or middleware, and finally/finalizers for cleanup. It favors clear, actionable messages for users while preventing leakage of technical or sensitive details. It also prescribes retry strategies (with exponential backoff) and escalation when failures persist.

When to use it

  • Adding try/catch blocks or rethrowing exceptions
  • Creating custom error classes or domain-specific error types
  • Implementing centralized error middleware, boundaries, or API handlers
  • Validating inputs and performing precondition checks (fail-fast)
  • Handling external service, database, or third-party failures
  • Designing graceful degradation and retry logic (exponential backoff)

Best practices

  • Fail fast: validate inputs and preconditions before doing work
  • Use specific error types so handlers can respond appropriately
  • Centralize top-level error handling at API or controller boundaries
  • Return clear, actionable user-facing messages; hide technical internals
  • Clean up resources in finally blocks or equivalent deterministic teardown
  • Apply retries with exponential backoff and circuit breaking for unstable external calls

Example use cases

  • Wrap controller endpoints with a centralized error middleware that maps exceptions to HTTP responses
  • Define domain errors (e.g., ValidationError, NotFoundError) and switch on type to set status codes
  • Validate incoming payloads immediately and throw a ValidationError to avoid wasted work
  • Implement retry logic for transient network calls with exponential backoff and a max retry limit
  • Use an error boundary in UI frameworks to show a friendly fallback UI while logging diagnostics

FAQ

How should I balance logging and user privacy?

Log detailed diagnostics (stack traces, timestamps, correlated IDs) to secure systems, but return only concise, non-sensitive messages to users.

When should I retry a failed external call?

Retry for transient errors (network timeouts, rate limits) with exponential backoff and jitter; avoid retrying for permanent failures (authentication, bad requests).