Phân loại lỗi¶

Mọi lỗi API dùng envelope JSON thống nhất. Ứng dụng client nên hiển thị thông báo theo error.code, không dùng trực tiếp error.message (tiếng Anh, dành cho log).

Envelope lỗi¶

{
  "success": false,
  "error": {
    "code": "JOB_NOT_FOUND",
    "message": "Job not found",
    "details": []
  }
}

Trường	Mô tả
`success`	Luôn `false` khi lỗi
`error.code`	Mã máy đọc được — dùng làm khóa i18n
`error.message`	Chuỗi chẩn đoán tiếng Anh
`error.details`	Mảng thông báo validation bổ sung
`error.correlationId`	Có trên lỗi `500` để hỗ trợ

Ánh xạ HTTP status¶

HTTP	`error.code` thường gặp	Khi nào
400	`VALIDATION_ERROR`, `INVALID_ASIN`, …	Body/query không hợp lệ
401	`UNAUTHORIZED`, `INVALID_CREDENTIALS`, …	Thiếu/sai JWT hoặc đăng nhập
402	`INSUFFICIENT_CREDITS`, …	Không đủ credits
403	`FORBIDDEN`	Không có quyền
404	`JOB_NOT_FOUND`, `PROJECT_NOT_FOUND`, …	Không tìm thấy tài nguyên
409	`EMAIL_ALREADY_EXISTS`, …	Xung đột
429	`RATE_LIMIT_EXCEEDED`	Bị throttle
500	`INTERNAL_ERROR`	Lỗi máy chủ

Danh sách đầy đủ: backends/apps/api/src/common/errors/error-codes.ts.

Xử lý phía client¶

Parse JSON; nếu success === false, đọc error.code.
Map sang chuỗi đã dịch.
Với 500, log correlationId nếu có.
Với 402, hướng người dùng nạp credits hoặc giảm quy mô job.

English: Error taxonomy