# Common Error Handling

> Cross-cutting standards for error design, response shapes, error codes, and boundary placement. (triggers: **/*.service.ts, **/*.handler.ts, **/*.controller.ts, **/*.go, **/*.java, **/*.kt, **/*.py, error handling, exception, try catch, error boundary, error response, error code, throw)

- Skill: `hoangnguyen0403/common-error-handling-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hoangnguyen0403/common-error-handling-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangnguyen0403/common-error-handling-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: HoangNguyen0403 (https://skillmd.com/u/hoangnguyen0403)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/hoangnguyen0403/common-error-handling-2

---


# Error Handling Standards

## **Priority: P1 (OPERATIONAL)**

## 🏗 Error Architecture

- **API Layer**: Map domain errors to HTTP responses globally.
- **Domain Layer**: Throw pure business errors. NO HTTP status codes here.
- **Infra Layer**: Wrap 3rd-party exceptions. Do NOT leak raw DB errors to API.
- **Standard Shape**: APIs must return a standardized JSON envelope (`code`, `message`, `traceId`).

## 📦 Error Mechanics

- **Wrap**: Add context (`fmt.Errorf("process: %w", err)`, `new Error('msg', { cause })`).
- **Replace**: Only when original error leaks sensitive details.
- **Error Codes**: Use `SCREAMING_SNAKE_CASE` IDs (`ORDER_PAYMENT_FAILED`).

## 🚫 Anti-Patterns

- **Swallowing Errors**: Never `catch(e) {}` without logging or re-throwing.
- **Stack Traces**: Never expose stack traces in API responses.
- **Generic 500s**: Use `400` with specific details for validation instead of 500.

## References
- [API Error Contract](references/api-error-contract.md)