Mã lỗi BankHub

Mã lỗi BankHub HiTechCloud Pay: bảng mã HTTP, mã lỗi nghiệp vụ và sự kiện lỗi trong luồng Hosted Link kèm cách xử lý từng trường hợp.

Xem Markdown

API BankHub trả lỗi theo chuẩn HTTP kèm phần thân JSON mô tả chi tiết. Hãy luôn kiểm tra mã trạng thái HTTP và trường error.code để xử lý phù hợp.

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

Ví dụ thân lỗi
{
  "status": "error",
  "error": {
    "code": "ACCOUNT_NOT_FOUND",
    "message": "Không tìm thấy tài khoản liên kết với id đã cho",
    "request_id": "req_7f3a9b22"
  }
}

Mã trạng thái HTTP

HTTPÝ nghĩaNguyên nhân thường gặp
400Bad RequestThiếu tham số bắt buộc hoặc sai định dạng body
401UnauthorizedAccess Token sai, hết hạn hoặc thiếu header Authorization
403ForbiddenToken không có quyền (scope) truy cập tài nguyên
404Not Foundaccount_id hoặc tài nguyên không tồn tại
409ConflictTài khoản đã được liên kết trước đó
429Too Many RequestsVượt giới hạn tần suất gọi (rate limit)
500Internal Server ErrorLỗi phía BankHub, thử lại sau hoặc liên hệ hỗ trợ
503Service UnavailableNgân hàng đang bảo trì hoặc tạm thời không kết nối được

Mã lỗi nghiệp vụ

error.codeMô tảHướng xử lý
INVALID_CREDENTIALSSai Client ID/Secret khi lấy tokenKiểm tra lại thông tin đối tác
LINK_TOKEN_EXPIREDLink Token quá 30 phútTạo Link Token mới
ACCOUNT_NOT_FOUNDKhông tìm thấy tài khoản liên kếtĐồng bộ lại danh sách tài khoản
BANK_UNAVAILABLENgân hàng đang bảo trìThử lại sau, báo người dùng
CONSENT_REVOKEDNgười dùng đã thu hồi quyềnYêu cầu người dùng liên kết lại
RATE_LIMIT_EXCEEDEDVượt giới hạn tần suấtGiãn tần suất gọi, dùng cache số dư
Luôn ghi lại request_id trong log của bạn — khi cần hỗ trợ, cung cấp mã này giúp đội kỹ thuật HiTechCloud tra cứu nhanh nguyên nhân.