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ý.
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ĩa | Cách xử lý |
|---|---|---|
400 | Payload sai định dạng hoặc thiếu trường bắt buộc | Kiểm tra lại các tham số theo bảng đặc tả endpoint |
401 | Token thiếu, sai hoặc đã hết hạn | Lấy lại Bearer Token mới qua /v1/token |
403 | Không có quyền với tài khoản NCC này | Kiểm tra provider_account_id thuộc tổ chức của bạn |
404 | Không tìm thấy hóa đơn / tài nguyên | Kiểm tra reference_code hoặc tracking_code |
409 | Xung độ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 |
429 | Vượt giới hạn tốc độ gọi | Giảm tần suất, tôn trọng header Retry-After |
500/503 | Lỗi hệ thống hoặc CQT tạm thời không phản hồi | Thử lại sau vài giây theo cấp số nhân |
Mã lỗi nghiệp vụ
| Mã lỗi | Mô tả | Cách xử lý |
|---|---|---|
E_DUPLICATE_REFERENCE | reference_code đã tồn tại | Dùng một mã đối soát duy nhất |
E_INVALID_TAX_CODE | Mã 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_INACTIVE | Tài khoản NCC chưa kích hoạt hoặc chưa được CQT duyệt | Kiểm tra trạng thái active qua API danh sách NCC |
E_SERIES_EXHAUSTED | Hế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_EXPIRED | Chứng thư số (CKS) đã hết hạn | Gia hạn CKS/HSM với nhà cung cấp |
E_CQT_REJECTED | Cơ quan Thuế từ chối cấp mã | Đọc message để biết chi tiết và sửa dữ liệu |
E_INVOICE_NOT_CANCELABLE | Hóa đơn không ở trạng thái cho phép hủy | Dù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.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
Mã lỗi HTTP
| HTTP | Ý nghĩa | Cách xử lý |
|---|---|---|
400 | Payload sai định dạng hoặc thiếu trường bắt buộc | Kiểm tra lại các tham số theo bảng đặc tả endpoint |
401 | Token thiếu, sai hoặc đã hết hạn | Lấy lại Bearer Token mới qua /v1/token |
403 | Không có quyền với tài khoản NCC này | Kiểm tra provider_account_id thuộc tổ chức của bạn |
404 | Không tìm thấy hóa đơn / tài nguyên | Kiểm tra reference_code hoặc tracking_code |
409 | Xung độ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 |
429 | Vượt giới hạn tốc độ gọi | Giảm tần suất, tôn trọng header Retry-After |
500/503 | Lỗi hệ thống hoặc CQT tạm thời không phản hồi | Thử lại sau vài giây theo cấp số nhân |
Mã lỗi nghiệp vụ
| Mã lỗi | Mô tả | Cách xử lý |
|---|---|---|
E_DUPLICATE_REFERENCE | reference_code đã tồn tại | Dùng một mã đối soát duy nhất |
E_INVALID_TAX_CODE | Mã 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_INACTIVE | Tài khoản NCC chưa kích hoạt hoặc chưa được CQT duyệt | Kiểm tra trạng thái active qua API danh sách NCC |
E_SERIES_EXHAUSTED | Hế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_EXPIRED | Chứng thư số (CKS) đã hết hạn | Gia hạn CKS/HSM với nhà cung cấp |
E_CQT_REJECTED | Cơ quan Thuế từ chối cấp mã | Đọc message để biết chi tiết và sửa dữ liệu |
E_INVOICE_NOT_CANCELABLE | Hóa đơn không ở trạng thái cho phép hủy | Dù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.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"
}
}