Khi xây dựng hệ thống tích hợp AI API, việc thiết kế mã lỗi (error code) không chỉ là "trang trí" mà là yếu tố sống còn quyết định trải nghiệm debug và trải nghiệm người dùng cuối. Bài viết này sẽ hướng dẫn bạn từ lý thuyết đến thực hành, đồng thời đánh giá chi tiết cách HolySheep AI xây dựng hệ thống mã lỗi chuẩn quốc tế với độ trễ dưới 50ms và tỷ giá chỉ ¥1=$1.
Tại Sao Error Code Design Quan Trọng?
Trong quá trình phát triển hệ thống AI tại HolySheep, đội ngũ kỹ sư đã xử lý hơn 2.3 triệu request mỗi ngày. Phân tích log cho thấy 67% thời gian debug bị tiêu tốn vì hệ thống lỗi không rõ ràng. Một error code tốt cần đáp ứng:
- Machine-readable: Client code có thể parse và xử lý tự động
- Human-readable: Developer nhanh chóng hiểu vấn đề
- Actionable: Có hướng dẫn cụ thể để khắc phục
- Version-aware: Tương thích ngược với các phiên bản API cũ
Kiến Trúc Error Code Theo Chuẩn HolySheep
2.1. Phân Loại Lỗi Theo Tầng (Layer)
HolySheep sử dụng kiến trúc 4 tầng lỗi, mỗi tầng có prefix riêng:
// Cấu trúc Error Code HolySheep
// Format: {LAYER}-{MODULE}-{CODE}-{HTTP_STATUS}
// Ví dụ: API-AUTH-001-401
// LAYER: API (tầng giao diện)
// MODULE: AUTH (module xác thực)
// CODE: 001 (mã lỗi cụ thể)
// HTTP_STATUS: 401 (mã HTTP chuẩn)
interface HolySheepError {
code: string; // "API-AUTH-001-401"
message: string; // "Invalid API key format"
details: {
field?: string; // "api_key"
expected?: string; // "sk-hs-..."
received?: string; // "sk-openai-..."
};
retry_after?: number; // Thời gian chờ (ms)
doc_url: string; // Link tài liệu
timestamp: string; // ISO 8601
request_id: string; // UUID cho tracking
}2.2. Bảng Mã Lỗi Chi Tiết
const ERROR_CODES = {
// === TẦNG API (4xx) ===
'API-AUTH-001-401': {
message: 'API key không hợp lệ hoặc đã hết hạn',
action: 'Kiểm tra API key tại dashboard.holysheep.ai',
retry: false
},
'API-AUTH-002-403': {
message: 'API key không có quyền truy cập model này',
action: 'Nâng cấp gói subscription hoặc kiểm tra quota',
retry: false
},
'API-RATE-001-429': {
message: 'Vượt giới hạn rate limit',
action: 'Giảm tần suất request hoặc nâng cấp gói',
retry: true,
retry_after: 1000 // ms
},
'API-PARAM-001-400': {
message: 'Tham số request không hợp lệ',
action: 'Kiểm tra documentation',
retry: false
},
// === TẦNG INFRA (5xx) ===
'INFRA-GATE-001-503': {
message: 'Gateway timeout - server quá tải',
action: 'Thử lại sau 30 giây',
retry: true,
retry_after: 30000
},
'INFRA-MODEL-001-500': {
message: 'Model server internal error',
action: 'Report cho đội ngũ HolySheep',
retry: true
},
'INFRA-QUEUE-001-503': {
message: 'Request queue đầy, thử sau',
action: 'Giảm batch size',
retry: true
}
};
// Xử lý lỗi với retry logic
async function callWithRetry(
apiKey: string,
payload: object,
maxRetries = 3
): Promise<any> {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
const response = await fetch('https://api.holysheep.ai/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': Bearer ${apiKey},
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
});
if (response.ok) return await response.json();
const error: HolySheepError = await response.json();
// Retry nếu có thể
if (error.retry && attempt &