Các lỗi thường gặp

Định dạng phản hồi lỗi

Các lỗi API đều tuân theo một cấu trúc phản hồi.

{
  "errorCode": "INVALID_REQUEST",
  "errorMessage": "Invalid request parameters",
  "requestId": "abc-123-xyz"
}

Mã "Thành công"

⚠️ Không có mã "Thành công" chung cho toàn bộ dịch vụ B2B — giá trị này khác nhau theo từng nhóm API (VD: 100 hoặc 200 tuỳ nhóm). Xem chính xác giá trị áp dụng tại bảng mã lỗi tương ứng.

Bảng mã lỗi thường gặp

Các mã lỗi hệ thống dưới đây dùng chung cho mọi nhóm API (không phải mã nghiệp vụ riêng của từng sản phẩm):

Mã lỗi	Ý nghĩa	Hành động đề xuất
11	Thất bại	Kiểm tra lại tham số request
101	Lỗi hệ thống Baokim	Retry sau vài giây; liên hệ Baokim nếu kéo dài
103	Lỗi xác thực chữ ký	Kiểm tra lại private key và thuật toán ký
104	Lỗi xác thực OAuth / JWT	Lấy lại token mới, kiểm tra client_id / client_secret
105	Lỗi xác thực chữ ký	Kiểm tra lại cách tạo chữ ký SHA256withRSA
422	Lỗi validate tham số	Kiểm tra các trường bắt buộc và định dạng dữ liệu
504	Timeout	Gọi API tra cứu để kiểm tra trạng thái trước khi retry
710	Sub Merchant không tồn tại	Kiểm tra sub_merchant_code
711	Master Merchant không tồn tại	Kiểm tra master_merchant_code
712	Sub Merchant không hoạt động	Liên hệ Baokim kiểm tra trạng thái tài khoản
713	Master Merchant không hoạt động	Liên hệ Baokim kiểm tra trạng thái tài khoản

Ngoài ra mỗi nhóm API có mã lỗi nghiệp vụ riêng (bao gồm cả mã "Thành công") — xem chi tiết tại trang Mã lỗi [Tên nhóm] của từng API.

Bảng trạng thái HTTP

Baokim sử dụng HTTP status code kết hợp với code trong response body:

HTTP Status	Ý nghĩa	Mô tả
200	OK	Request được xử lý. Kiểm tra code trong body để biết thành công hay lỗi nghiệp vụ
401	Unauthorized	JWT Token thiếu hoặc không hợp lệ
403	Forbidden	Token hợp lệ nhưng không có quyền gọi endpoint này
404	Not Found	Endpoint không tồn tại
422	Unprocessable Entity	Dữ liệu request không hợp lệ (validate thất bại)
429	Too Many Requests	Vượt quá rate limit
500	Internal Server Error	Lỗi nội bộ phía Baokim
504	Gateway Timeout	Timeout — gọi API tra cứu để xác nhận trạng thái trước khi retry

Lưu ý: Hầu hết lỗi nghiệp vụ (sai tham số, giao dịch không tồn tại...) đều trả về HTTP 200 với code khác mã "Thành công" của nhóm API đó (100 hoặc 200 tuỳ nhóm) trong body — không phải HTTP 4xx/5xx.

Xử lý sự cố

Chữ ký không hợp lệ (lỗi 103 / 105)

• Kiểm tra thuật toán ký: SHA256withRSA (hoặc SHA1withRSA với VA direct).
• Đảm bảo ký toàn bộ raw JSON string của request body, không phải object đã parse.
• Đảm bảo base64 encode chuỗi chữ ký trước khi đặt vào header Signature.
• Kiểm tra private key đúng format (PEM) và khớp với public key đã cung cấp cho Baokim.

Token hết hạn (lỗi 104)

• JWT Token có thời hạn ngắn. Implement logic tự động refresh token khi gặp lỗi 104 hoặc khi expired_at sắp đến.
• Không hardcode token — luôn lấy token mới từ API OAuth trước khi gọi.

Tạo đơn thành công nhưng không nhận được webhook

• Kiểm tra URL webhook đã cấu hình với Baokim có đúng và accessible từ internet không.
• Kiểm tra server có trả về HTTP 200 đúng cách không (không redirect, không lỗi SSL).
• Kiểm tra log server xem có nhận request từ IP của Baokim không.
• Gọi API tra cứu giao dịch để xác nhận trạng thái thực tế của đơn.

Timeout khi tạo giao dịch

• Không retry ngay lập tức — gọi API tra cứu trước để kiểm tra giao dịch đã tồn tại chưa.
• Nếu giao dịch chưa tồn tại, retry với cùng request_id để đảm bảo idempotency.
• Tăng timeout client lên 30–60 giây cho các API tạo giao dịch.

Lỗi 422 — Validate thất bại

• Kiểm tra tất cả trường bắt buộc (✅) đã được truyền đủ.
• Kiểm tra định dạng request_time: YYYY-MM-DD H:i:s.
• Kiểm tra request_id chưa được dùng trước đó (phải unique mỗi request mới).
• Xem thêm message trong response để biết trường nào bị lỗi cụ thể.