Mã Lỗi & Xử Lý Sự Cố

Tất cả các phản hồi lỗi từ ImageCoreAPI đều tuân thủ cấu trúc chuẩn hóa (Unified Error Envelope), giúp client dễ dàng bắt lỗi và phân nhánh xử lý tự động.

---

1. Cấu Trúc Phản Hồi Lỗi Chuẩn

Khi xảy ra lỗi (mã HTTP $\ge 400$), API trả về đối tượng JSON:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Mô tả chi tiết nguyên nhân phát sinh lỗi."
  },
  "data": null
}

• error.code: Mã định danh dạng chuỗi in hoa (UPPER_SNAKE_CASE), cố định để lập trình viên sử dụng trong switch/case hoặc if/else.
• error.message: Thông điệp giải thích lỗi cụ thể bằng tiếng Anh/Việt.
• data: Luôn là null trong response lỗi.

---

2. Bảng Mã Lỗi Phổ Biến Của Gateway

HTTP Status	Error Code	Nguyên nhân cụ thể	Hướng xử lý
401	INVALID_KEY	Thiếu Header, sai định dạng key, key không tồn tại hoặc đã hết hạn / bị khóa	Kiểm tra lại giá trị Header X-API-Key
403	PLATFORM_NOT_ALLOWED	Key chưa được cấp quyền truy cập sàn này	Liên hệ admin để mở quyền sàn tương ứng
413	PAYLOAD_TOO_LARGE	Tệp ảnh upload vượt quá dung lượng cho phép (12MB đối với TikTok upload)	Nén ảnh hoặc giảm độ phân giải trước khi tải lên
422	VALIDATION_ERROR	Thiếu hoặc sai định dạng các trường bắt buộc trong Request Body (ví dụ thiếu cookie, thiếu ảnh)	Kiểm tra lại JSON payload theo đúng tài liệu API
429	RATE_LIMITED	Vượt quá số request/phút cấu hình cho key (rate_rpm)	Đọc header Retry-After và chờ trước khi gửi lại
429	QUOTA_EXCEEDED	Đã dùng hết số lượt tìm kiếm cho phép trong chu kỳ	Liên hệ quản trị viên để gia hạn thêm quota
429	AUTH_THROTTLED	Địa chỉ IP gửi quá 20 request sai key trong 60 giây	Tạm dừng gửi request trong 60 giây
502	UPSTREAM_ERROR	Kết nối tới máy chủ sàn thương mại điện tử bị gián đoạn hoặc timeout	Thử lại sau ít phút hoặc kiểm tra tình trạng sàn qua /v1/health
500	INTERNAL_SERVER_ERROR	Lỗi máy chủ không xác định	Liên hệ bộ phận kỹ thuật để được hỗ trợ

---

3. Các Lỗi Nghiệp Vụ Thực Tế & Cách Khắc Phục

Đối với Shopee Search:

1. Lỗi cookie không hợp lệ hoặc hết hạn:
   • Biểu hiện: Upstream trả về mã lỗi yêu cầu đăng nhập hoặc không trả về danh sách sản phẩm.
   • Khắc phục: Cập nhật chuỗi Cookie tài khoản Shopee mới trong trường cookie.
2. Lỗi thiếu trường ảnh:
   • Biểu hiện: HTTP 422 One of image_key, image_url, or image_base64 is required.
   • Khắc phục: Đảm bảo bạn đã truyền ít nhất 1 trong 3 trường hình ảnh.

Đối với TikTok Search & Upload:

1. Lỗi chuỗi Base64 chứa tiền tố Data URI:
   • Biểu hiện: Upstream không nhận diện được file ảnh hoặc trả về lỗi định dạng ảnh.
   • Khắc phục: Hãy truyền chuỗi Base64 thuần túy. Nếu chuỗi có dạng data:image/jpeg;base64,/9j/4AAQ..., hãy cắt bỏ phần data:image/jpeg;base64, trước khi gửi.
2. Ảnh không có sản phẩm:
   • Biểu hiện: Kết quả trả về mảng products rỗng [].
   • Khắc phục: Thử lại với bức ảnh rõ nét hơn, vật thể chiếm diện tích chính giữa khung hình.