/error-handling

name: error-handling
description: Graceful degradation and meaningful error messages. Errors are first-class citizens, not afterthoughts. Every error path is designed, not discovered.
category: harden
applies-to: [claude, gemini, cursor, copilot, any]
version: 1.0.0

Overview

Error handling is not defensive programming — it's a user experience. When things go wrong (and they will), the system should degrade gracefully, give users actionable information, and leave enough telemetry to diagnose and fix the problem.

When to Use

• When writing any code that can fail (I/O, network, parsing, user input)
• When reviewing error handling in existing code
• Before any service goes to production

Process

Step 1: Design Error Paths Explicitly

1. For every operation, list: what can fail? What does failure look like? 2. Classify failures:

• **Transient**: Retry likely to succeed (network blip, temporary unavailability)
• **Client error**: Bad input from the caller (4xx) — don't retry
• **System error**: Internal failure (5xx) — alert, investigate

3. Design the failure path for each class before writing the happy path.

**Verify:** Error classes defined for every external operation.

Step 2: Meaningful Error Messages

4. Every error message answers: what went wrong? How can the caller fix it?

• ✅ "Invalid email format. Expected: user@domain.com"
• ❌ "Validation error"

5. User-facing errors: friendly language, no stack traces. 6. Developer-facing errors (logs): full context, request ID, stack trace. 7. Never expose internal system details (DB schema, file paths) in user-facing errors.

**Verify:** Each error message would help a user or developer understand and fix the problem.

Step 3: Retry with Backoff

8. Transient errors: retry with exponential backoff + jitter. 9. Maximum retries: 3 (not infinite). 10. After max retries: fail with a clear error, log the final failure. 11. Non-transient errors (validation, auth): never retry.

**Verify:** Retry logic has a maximum. Non-transient errors don't retry.

Step 4: Graceful Degradation

12. Identify non-critical dependencies. If they fail, degrade — don't crash. 13. Example: recommendation engine fails → show default content, not 500. 14. Circuit breaker pattern for failing dependencies: fail fast after threshold, recover automatically.

**Verify:** Every non-critical dependency has a defined degraded state.

Step 5: Structured Error Responses (APIs)

15. API errors return consistent structure:

    {
      "error": {
        "code": "INVALID_EMAIL",
        "message": "The email address format is invalid.",
        "requestId": "req_abc123"
      }
    }

16. HTTP status codes used correctly: 400 (client error), 404 (not found), 429 (rate limited), 500 (server error).

Common Rationalizations (and Rebuttals)

| Excuse | Rebuttal | |--------|----------| | "I'll add error handling later" | Later means in production, under pressure, while users are impacted. | | "This can't fail" | Everything can fail. Network calls, disk writes, parsing — all can fail. | | "The error message doesn't matter" | It matters when a developer is debugging at 2am. |

Verification

• [ ] Error classes defined for every external operation
• [ ] Error messages answer: what went wrong? How to fix?
• [ ] Transient errors retry with max limit
• [ ] Non-critical dependencies have graceful degraded states
• [ ] API errors return consistent structured format
• [ ] No internal system details in user-facing errors

References

• [observability skill](../observability/SKILL.md)
• [debugging-methodology skill](../debugging-methodology/SKILL.md)