error-handling

name	error-handling
description	Use when creating, updating, reviewing, or debugging error handling, exceptions, error responses, domain errors, validation errors, logging, error boundaries, async failures, or failure propagation.

Error Handling

Use this skill for safe and consistent error handling.

Rules

• Follow the project’s existing error handling pattern.
• Do not add a new error library, logging system, monitoring tool, or response format unless already used or explicitly requested.
• Separate expected business errors from unexpected system errors.
• Return safe user-facing messages.
• Never expose stack traces, secrets, tokens, database internals, provider internals, or raw system errors to clients.
• Never leave empty catch blocks.
• Do not swallow errors silently.
• Use the project’s existing logging pattern for internal details.
• Preserve existing response, error, logging, and test conventions.
• Avoid unrelated refactors.

Inspect First

Before changing error handling, check existing patterns for:

• error classes/utilities
• API error response shape
• HTTP status mapping
• validation error format
• logging pattern
• frontend error display
• error boundaries
• retry behavior
• test style

Implementation Checklist

• Identify whether the error is expected or unexpected.
• Use existing domain/application error types when available.
• Map errors to the project’s existing response format.
• Use correct HTTP/status codes where relevant.
• Keep validation errors clear and field-specific when supported.
• Log unexpected errors with safe context.
• Clean up loading/pending states after async failures.
• Add or update relevant tests.

Status Defaults

Use project mappings first. If missing:

Case	Status
Invalid input	400
Missing authentication	401
Missing permission	403
Not found	404
Conflict or duplicate	409
Rate limited	429
External provider failure	502
Temporary service failure	503
Unexpected error	500

Security Rules

• Never expose stack traces to users.
• Never expose raw SQL, database, provider, or runtime errors.
• Use generic messages for credential failures.
• Avoid revealing whether private accounts, emails, tokens, or resources exist.
• Do not log passwords, secrets, tokens, cookies, card data, private keys, or sensitive payloads.

Async Rules

• Handle rejected promises.
• Use cleanup/finally for loading and pending states.
• Either handle, log, transform, retry, or rethrow errors.
• Retry only safe/idempotent temporary failures.
• Do not retry invalid input, permission failures, or unsafe writes.

Frontend Rules

• Show safe and useful messages.
• Preserve user input after validation failures.
• Provide retry actions when useful.
• Use local error states or error boundaries according to project pattern.
• Do not display internal error details.

Tests

Cover relevant paths:

• validation error
• auth/permission error
• not found
• conflict
• provider failure
• unexpected fallback
• async cleanup
• frontend error state
• sensitive details not exposed
• correct status mapping