[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]

# Tim error code theo keyword
grep -r "AUTH_" src/lib/errors/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"
      }
    }
  }
}

python scripts/generate-types.py

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')

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'
})

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))
}

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

return createError('CUSTOM_ERROR', 'Custom message', {
  status: 418,
  details: 'Technical details',
  suggestion: 'How to fix'
})

{
  "success": true,
  "data": { ... },
  "message": "Thanh cong"
}

{
  "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"
  }
}

return errorResponse('Email da ton tai', 409)

return businessError('AUTH', 'AUTH_002')

// File: src/lib/api-response.ts
export {
  createError,
  httpError,
  validationError,
  businessError,
  withErrorHandler,
} from './errors'

// 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
}

// 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
}