| 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