Mã lỗi

PayerScan API sử dụng định dạng phản hồi lỗi chuẩn hóa. Tất cả lỗi tuân theo cấu trúc nhất quán để dễ xử lý trên backend của merchant.

Cấu trúc phản hồi lỗi

{
  "status": "error",
  "message": "Invalid API key. Please check your API key and try again.",
  "error_code": "INVALID_API_KEY",
  "request_id": "ORDER_123456",
  "details": { ... }
}

Các thuộc tính:

• status: Luôn là "error".
• message: Mô tả lỗi dạng đọc được.
• error_code: Mã lỗi máy đọc được, định dạng UPPER_SNAKE_CASE. Dùng switch/case để xử lý tự động.
• request_id (tùy chọn): Mã đơn hàng của bạn, chỉ trả về nếu đã cung cấp khi tạo hóa đơn.
• details (tùy chọn): Thông tin chi tiết về lỗi (ví dụ: lỗi validation, tên trường).

Danh sách mã lỗi

Lỗi xác thực

Mã lỗi	HTTP	Message	Cách xử lý
MISSING_API_KEY	401	Missing API key. Please provide x-api-key header.	Thêm header x-api-key vào request.
INVALID_API_KEY	401	Invalid API key. Please check your API key and try again.	Kiểm tra API key trên Dashboard.
ACCOUNT_INACTIVE	403	Merchant account is inactive. Please contact support to reactivate.	Liên hệ hỗ trợ PayerScan.
STORE_INACTIVE	403	Store is inactive. Please contact support to reactivate your store.	Kích hoạt lại store trên Dashboard.
AUTHENTICATION_FAILED	500	Authentication failed. Please try again later.	Thử lại sau; nếu vẫn lỗi, liên hệ hỗ trợ.

Lỗi validation

Mã lỗi	HTTP	Message	Cách xử lý
VALIDATION_ERROR	400	Validation failed. Please check your request body.	Kiểm tra details.errors để biết lỗi cụ thể.
INVALID_MERCHANT_ID	400	Invalid merchant_id. The merchant_id does not match your API key.	Đảm bảo merchant_id khớp với store của API key.

Lỗi nghiệp vụ

Mã lỗi	HTTP	Message	Cách xử lý
INSUFFICIENT_BALANCE	402	Insufficient balance. Please top-up your account to continue.	Nạp tiền trên PayerScan Dashboard. Kiểm tra details để biết số tiền thiếu.
NO_PAYMENT_METHOD	400	No payment method configured. Please add at least one wallet or exchange platform.	Thêm ví hoặc kết nối sàn giao dịch trên Dashboard.

Lỗi hóa đơn

Mã lỗi	HTTP	Message	Cách xử lý
INVOICE_NOT_FOUND	404	Invoice not found.	Kiểm tra trans_id và đảm bảo thuộc store của bạn.
MISSING_TRANS_ID	400	Missing trans_id in URL.	Thêm trans_id vào đường dẫn URL: GET /invoice/:trans_id.
INVALID_TRANS_ID_FORMAT	400	Invalid trans_id format.	Sử dụng đúng định dạng: TID-XXXXXXXXXXXXXXXX.

Lỗi giới hạn tốc độ

Mã lỗi	HTTP	Message	Cách xử lý
RATE_LIMIT_EXCEEDED	429	Too many requests per second. / Rate limit exceeded.	Đợi retry_after_seconds rồi thử lại. Xem Giới hạn tốc độ.

Lỗi server

Mã lỗi	HTTP	Message	Cách xử lý
INTERNAL_ERROR	500	Internal server error. Please try again later.	Thử lại với exponential backoff. Nếu vẫn lỗi, liên hệ hỗ trợ.