vuthuonghai-steve/error-response-system

🚨 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:

1. Developer: Debug nhanh hon voi error codes cu the
2. Frontend: Hien thi message va suggestion cho user
3. Team: Thong nhat format error response toan project
4. 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:

# Tim error code theo keyword
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'

// 400 Bad Request
return httpError('BAD_REQUEST')

// 401 Unauthorized
return httpError('UNAUTHORIZED')

// 404 Not Found
return httpError('NOT_FOUND')

// Custom message
return httpError('NOT_FOUND', 'San pham khong ton tai')

Business Errors

import { businessError } from '@/lib/errors'

// Voi error code
return businessError('AUTH', 'AUTH_002')

// Voi custom message
return businessError('ORD', 'ORD_001', {
  details: 'Order ID: 12345'
})

Validation Errors

import { validationError, formatZodErrors } from '@/lib/errors'

// Single field
return validationError('email', 'Email khong hop le')

// Multiple fields (tu Zod)
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: [email protected] 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:

// File: src/lib/api-response.ts
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

// src/app/api/v1/auth/register/route.ts
import { businessError, validationError } from '@/lib/errors'

export async function POST(req: Request) {
  const data = await req.json()

  // Validation error
  const result = registerSchema.safeParse(data)
  if (!result.success) {
    return validationError(formatZodErrors(result.error))
  }

  // Check email exists
  const existing = await payload.find({
    collection: 'users',
    where: { email: { equals: data.email } }
  })

  if (existing.docs.length > 0) {
    return businessError('AUTH', 'AUTH_002')
  }

  // ... create user
}

2. Tao Don Hang

// src/app/api/v1/orders/route.ts
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')
  }

  // Check stock
  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}`
      })
    }
  }

  // ... create order
}

---

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

1. LUON dung error code tu error-codes.json - Khong hardcode message
2. GIU nguyen code cu - Format moi la bo sung, khong thay the
3. Validate truoc khi commit - Chay scripts/validate-error-codes.py
4. Generate types sau khi them code - Chay scripts/generate-types.py
5. Message bang tieng Viet - De user hieu
6. Suggestion co ich - Giup user biet cach khac phuc