Lỗi

Mọi lỗi có cùng một cấu trúc:

{
  "error": {
    "code": "no_active_bank_account",
    "message": "Link a bank account before creating payment requests.",
    "request_id": "req_01JD7QF0X2C4M8R6T1Y3W5Z7NB"
  }
}

• code là hợp đồng ổn định – viết logic dựa trên nó.
• message dành cho người đọc, có thể thay đổi – đừng so sánh chuỗi.
• request_id – gửi kèm khi liên hệ hỗ trợ để Hensa tìm đúng request.

Danh sách mã lỗi

Mã (`code`)	HTTP	Ý nghĩa
validation_error	400	Dữ liệu gửi lên không hợp lệ – xem message.
unauthorized	401	Thiếu hoặc sai khóa API.
forbidden	403	Khóa không có quyền cho thao tác này.
test_mode_only	403	Chỉ dùng được với khóa hk_test_.
not_found	404	Không tìm thấy (hoặc không thuộc cửa hàng của khóa này).
idempotency_conflict	409	Cùng Idempotency-Key nhưng nội dung khác.
already_reconciled	409	Giao dịch đã được khớp trước đó.
no_active_bank_account	422	Cửa hàng chưa có tài khoản ngân hàng đang hoạt động.
merchant_name_required	422	Cửa hàng chưa đặt tên – đặt tên trong Dashboard trước khi tạo QR (chỉ ở chế độ thật).
plan_limit	422	Vượt giới hạn của gói hiện tại.
url_not_https	422	URL webhook phải dùng HTTPS.
url_private_address	422	URL trỏ tới địa chỉ nội bộ – không được phép.
delivery_too_old	422	Chỉ gửi lại được sự kiện trong 30 ngày.
rate_limited	429	Gọi quá nhanh – chờ theo header Retry-After.
internal_error	500	Lỗi phía Hensa – thử lại sau (an toàn nhờ Idempotency-Key).

Nên thử lại khi nào

HTTP	Thử lại?
400, 401, 403, 404, 422	Không – sửa request
409 idempotency_conflict	Chỉ khi lần đầu đang xử lý dở; nếu do khác nội dung thì không
429	Có – chờ theo header Retry-After
5xx, lỗi mạng, quá thời gian	Có – với cùng Idempotency-Key, backoff tăng dần