Mã lỗi eInvoice API

Mã lỗi API Hoá đơn điện tử HiTechCloud Pay: danh sách mã HTTP và mã lỗi nghiệp vụ khi phát hành, ký số hay tra cứu hoá đơn cùng cách xử lý.

Xem Markdown

Mọi phản hồi lỗi đều có success: false kèm đối tượng error chứa code (mã nghiệp vụ) và message (mô tả tiếng Việt). Dựa vào code để xử lý tự động, không nên parse theo message.

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

Phản hồi lỗi mẫu
{
  "success": false,
  "error": {
    "code": "E_INVALID_TAX_CODE",
    "message": "Mã số thuế người mua không hợp lệ",
    "field": "buyer.tax_code"
  }
}

Mã lỗi HTTP

HTTPÝ nghĩaCách xử lý
400Payload sai định dạng hoặc thiếu trường bắt buộcKiểm tra lại các tham số theo bảng đặc tả endpoint
401Token thiếu, sai hoặc đã hết hạnLấy lại Bearer Token mới qua /v1/token
403Không có quyền với tài khoản NCC nàyKiểm tra provider_account_id thuộc tổ chức của bạn
404Không tìm thấy hóa đơn / tài nguyênKiểm tra reference_code hoặc tracking_code
409Xung đột: hóa đơn đã tồn tại hoặc trạng thái không cho phépĐổi reference_code hoặc kiểm tra trạng thái hiện tại
429Vượt giới hạn tốc độ gọiGiảm tần suất, tôn trọng header Retry-After
500/503Lỗi hệ thống hoặc CQT tạm thời không phản hồiThử lại sau vài giây theo cấp số nhân

Mã lỗi nghiệp vụ

Mã lỗiMô tảCách xử lý
E_DUPLICATE_REFERENCEreference_code đã tồn tạiDùng một mã đối soát duy nhất
E_INVALID_TAX_CODEMã số thuế người mua không hợp lệKiểm tra định dạng 10 hoặc 13 chữ số
E_PROVIDER_ACCOUNT_INACTIVETài khoản NCC chưa kích hoạt hoặc chưa được CQT duyệtKiểm tra trạng thái active qua API danh sách NCC
E_SERIES_EXHAUSTEDHết dải số hóa đơn trong ký hiệuĐăng ký thêm dải/ký hiệu với nhà cung cấp
E_CERT_EXPIREDChứng thư số (CKS) đã hết hạnGia hạn CKS/HSM với nhà cung cấp
E_CQT_REJECTEDCơ quan Thuế từ chối cấp mãĐọc message để biết chi tiết và sửa dữ liệu
E_INVOICE_NOT_CANCELABLEHóa đơn không ở trạng thái cho phép hủyDùng phương án điều chỉnh/thay thế phù hợp
Với các lỗi 5xx và 429, hãy áp dụng cơ chế thử lại (retry) có độ trễ tăng dần và idempotency theo reference_code để tránh phát hành trùng hóa đơn.