| name | error-response-system |
| description | Skill chuan hoa Error Response cho API. Su dung khi can (1) tao error response moi, (2) them error code cho feature, (3) debug loi API, (4) migration tu format cu sang format moi. Skill nay nen duoc su dung khi nguoi dung can thong nhat error response format hoac tao he thong error handling moi. |
| category | implementation |
| pipeline | {"stage_order":11,"input_contract":[],"output_contract":[{"type":"directory","path":"src/lib/errors","format":"directory"}],"dependencies":[]} |
🚨 MỆNH LỆNH BẮT BUỘC TỪ HỆ THỐNG (CRITICAL DIRECTIVE):
Bạn CHỈ MỚI ĐỌC file SKILL.md này. Trí tuệ của bạn chưa được nạp đầy đủ.
Hệ thống KHÔNG tự động nạp các file kiến thức khác trong thư mục.
Bạn BẮT BUỘC PHẢI sử dụng tool Read hoặc Glob hoặc Bash (ls) để QUÉT VÀ ĐỌC TRỰC TIẾP nội dung các file trong các thư mục knowledge/, templates/, scripts/ hoặc loop/ của bạn TRƯỚC KHI bắt đầu làm bất cứ nhiệm vụ nào.
Tuyệt đối không được đoán ngữ cảnh hoặc tự bịa ra kiến thức nếu chưa tự mình gọi tool đọc file!
Error Response System
Overview
Skill nay cung cap he thong chuan hoa error responses cho toan bo API cua Agent-skill. No giup:
- Developer: Debug nhanh hon voi error codes cu the
- Frontend: Hien thi message va suggestion cho user
- Team: Thong nhat format error response toan project
- Maintenance: De dang them error codes moi qua JSON config
Khi Nao Su Dung Skill Nay
1. Tao Error Response Moi
- Khi can tra ve error tu API endpoint
- Khi can validation error voi field cu the
- Khi can business logic error (AUTH, ORD, PAY, etc.)
2. Them Error Code Cho Feature
- Khi phat trien feature moi can error handling
- Khi can error code cho nghiep vu cu the
- Khi can thong bao loi co y nghia cho user
3. Debug Loi API
- Khi can hieu y nghia cua error code
- Khi can tim nguyen nhan loi tu code
- Khi can goi y khac phuc loi
4. Migration Tu Format Cu
- Khi can chuyen doi errorResponse() -> businessError()
- Khi can them error code cho API hien tai
- Khi can thong nhat format toan project
Workflow Tong Quan
[Trigger: Can error handling]
|
v
[PHASE 1: Xac Dinh Error Type]
- HTTP Error (400, 401, 404, 500)?
- Business Error (AUTH, ORD, PAY)?
- Validation Error?
|
v
[PHASE 2: Chon/Tao Error Code]
- Tim trong error-codes.json
- Tao code moi neu chua co
- Dung dung prefix (AUTH_, ORD_, PAY_)
|
v
[PHASE 3: Su Dung Helper]
- httpError() cho HTTP errors
- businessError() cho business logic
- validationError() cho form validation
|
v
[Output: Structured Error Response]
PHASE 1: Xac Dinh Error Type
HTTP Errors (4xx, 5xx)
Su dung khi error lien quan den HTTP protocol:
| Code | Su dung khi |
|---|
| 400 | Request sai format, thieu params |
| 401 | Chua dang nhap, token het han |
| 403 | Khong co quyen truy cap |
| 404 | Resource khong ton tai |
| 409 | Conflict (duplicate, da ton tai) |
| 422 | Validation failed |
| 429 | Rate limit exceeded |
| 500 | Server error |
Business Errors
Su dung khi error lien quan den nghiep vu:
| Prefix | Domain | Vi du |
|---|
| AUTH_ | Authentication | AUTH_001: Email da ton tai |
| ORD_ | Orders | ORD_001: Don hang da huy |
| PAY_ | Payment | PAY_001: So du khong du |
| PTS_ | Points | PTS_001: Diem khong du |
| VCH_ | Voucher | VCH_001: Voucher het han |
| STR_ | Store | STR_001: Cua hang khong hoat dong |
| PRD_ | Product | PRD_001: San pham het hang |
| SYS_ | System | SYS_001: Service khong kha dung |
Validation Errors
Su dung khi form/request validation that bai:
- Field-level validation (email, password, etc.)
- Business rules validation
- Format validation (phone, date, etc.)
PHASE 2: Chon/Tao Error Code
Buoc 2.1: Tim Error Code Co San
Doc file src/lib/errors/error-codes.json:
grep -r "AUTH_" src/lib/errors/error-codes.json
Buoc 2.2: Tao Error Code Moi (Neu Can)
Neu chua co error code phu hop, them vao file error-codes.json:
{
"BUSINESS_ERRORS": {
"AUTH": {
"AUTH_010": {
"code": "AUTH_010",
"status": 400,
"message": "Thong bao cho user",
"details": "Chi tiet ky thuat cho developer",
"suggestion": "Goi y cach khac phuc"
}
}
}
}
Quy tac dat ten:
- Prefix: 3 ky tu viet hoa (AUTH, ORD, PAY, etc.)
- Number: 3 chu so (001, 002, 010, etc.)
- Format:
PREFIX_NNN
Buoc 2.3: Generate Types
Sau khi them error code moi, chay:
python scripts/generate-types.py
PHASE 3: Su Dung Helper Functions
HTTP Errors
import { httpError } from '@/lib/errors'
return httpError('BAD_REQUEST')
return httpError('UNAUTHORIZED')
return httpError('NOT_FOUND')
return httpError('NOT_FOUND', 'San pham khong ton tai')
Business Errors
import { businessError } from '@/lib/errors'
return businessError('AUTH', 'AUTH_002')
return businessError('ORD', 'ORD_001', {
details: 'Order ID: 12345'
})
Validation Errors
import { validationError, formatZodErrors } from '@/lib/errors'
return validationError('email', 'Email khong hop le')
const result = schema.safeParse(data)
if (!result.success) {
return validationError(formatZodErrors(result.error))
}
Custom Errors
import { createError } from '@/lib/errors'
return createError('CUSTOM_ERROR', 'Custom message', {
status: 418,
details: 'Technical details',
suggestion: 'How to fix'
})
Response Format
Success Response (Giu Nguyen)
{
"success": true,
"data": { ... },
"message": "Thanh cong"
}
Error Response (Moi)
{
"success": false,
"error": {
"code": "AUTH_002",
"message": "Email da duoc su dung",
"details": "Email: user@example.com da ton tai trong he thong",
"field": "email",
"suggestion": "Su dung email khac hoac dang nhap",
"timestamp": "2026-01-16T10:30:00.000Z",
"requestId": "req_abc123"
}
}
Migration Guide
Tu Format Cu Sang Format Moi
Truoc (cu - van hoat dong):
return errorResponse('Email da ton tai', 409)
Sau (moi - khuyen nghi):
return businessError('AUTH', 'AUTH_002')
Backward Compatibility
Code cu van hoat dong binh thuong. api-response.ts da re-export tu ./errors:
export {
createError,
httpError,
validationError,
businessError,
withErrorHandler,
} from './errors'
Files Quan Trong
Skill Resources
| File | Muc dich |
|---|
assets/error-codes-template.json | Template error codes |
scripts/validate-error-codes.py | Validate JSON format |
scripts/generate-types.py | Generate TypeScript types |
references/implementation-guide.md | Patterns chi tiet |
references/migration-guide.md | Huong dan migration |
Implementation Files (Khi Deploy)
| File | Muc dich |
|---|
src/lib/errors/index.ts | Re-export module |
src/lib/errors/types.ts | TypeScript interfaces |
src/lib/errors/helpers.ts | Helper functions |
src/lib/errors/handler.ts | Global error handler |
src/lib/errors/error-codes.json | Error codes config |
Vi Du Cu The
1. Dang Ky Nguoi Dung
import { businessError, validationError } from '@/lib/errors'
export async function POST(req: Request) {
const data = await req.json()
const result = registerSchema.safeParse(data)
if (!result.success) {
return validationError(formatZodErrors(result.error))
}
const existing = await payload.find({
collection: 'users',
where: { email: { equals: data.email } }
})
if (existing.docs.length > 0) {
return businessError('AUTH', 'AUTH_002')
}
}
2. Tao Don Hang
import { businessError, httpError } from '@/lib/errors'
export async function POST(req: Request) {
const user = await getCurrentUser(req)
if (!user) {
return httpError('UNAUTHORIZED')
}
const cart = await getCart(user.id)
if (cart.items.length === 0) {
return businessError('ORD', 'ORD_002')
}
for (const item of cart.items) {
const product = await getProduct(item.productId)
if (product.stock < item.quantity) {
return businessError('PRD', 'PRD_001', {
details: `San pham: ${product.name}`
})
}
}
}
Trigger Phrases
Skill nay duoc kich hoat khi:
Tao Error Response
- "tao error response"
- "tra ve loi tu API"
- "error handling cho endpoint"
Them Error Code
- "them error code"
- "tao error code moi"
- "error cho feature X"
Debug Loi
- "error code X nghia la gi"
- "debug loi API"
- "hieu error response"
Migration
- "migration error response"
- "chuyen doi sang format moi"
- "thong nhat error format"
Luu Y Quan Trong
- LUON dung error code tu error-codes.json - Khong hardcode message
- GIU nguyen code cu - Format moi la bo sung, khong thay the
- Validate truoc khi commit - Chay
scripts/validate-error-codes.py
- Generate types sau khi them code - Chay
scripts/generate-types.py
- Message bang tieng Viet - De user hieu
- Suggestion co ich - Giup user biet cach khac phuc