Error Handling
by @mike47512
Deep error handling workflow—taxonomy, user-visible vs internal errors, retries and idempotency, observability, and supportability. Use when standardizing fa...
clawhub install error-handling📖 About This Skill
name: error-handling description: Deep error handling workflow—taxonomy, user-visible vs internal errors, retries and idempotency, observability, and supportability. Use when standardizing failure modes across APIs, clients, and async workers.
Error Handling
Consistent errors reduce support load and on-call pain. Design a taxonomy, stable codes, safe user messaging, and operator visibility—without leaking secrets or stack traces to clients.
When to Offer This Workflow
Trigger conditions:
Initial offer:
Use six stages: (1) classify errors, (2) map to transport, (3) user messaging, (4) retries & idempotency, (5) observability, (6) client SDKs & DX). Confirm REST/GraphQL/gRPC and sync/async patterns.
Stage 1: Classify Errors
Goal: Distinguish validation, authentication, authorization, not found, conflict, rate limit, dependency failure, and internal bugs.
Exit condition: Table or enum of codes with owning team and meaning.
Stage 2: Map to Transport
Goal: Correct HTTP 4xx/5xx; GraphQL errors with extensions; gRPC status codes; optional RFC 7807 Problem Details for JSON APIs.
Stage 3: User Messaging
Goal: Actionable copy for end users; opaque support reference id; no internal hostnames, SQL fragments, or stack traces in client responses.
Stage 4: Retries & Idempotency
Goal: Retry only safe or idempotent operations; exponential backoff with jitter; align with idempotency keys on writes.
Stage 5: Observability
Goal: Structured logs with error.code, trace_id, user_id (where allowed); metrics by error class; alerts on error-rate SLO burn.
Stage 6: Client SDKs & DX
Goal: Typed errors in SDKs; documented recovery; map codes to user-facing strings in apps consistently.