hddt.dev
Tài liệuBảng giáTra cứu

Bắt đầu

  • Tổng quan
  • Bắt đầu nhanh
  • Xác thực
  • Môi trường sandbox
  • Mã lỗi

Ứng dụng

  • GETThông tin ứng dụng
  • PATCHCập nhật ứng dụng

Hoá đơn

  • POSTLấy token
  • GETLấy mẫu hoá đơn
  • GETDanh sách mẫu đã đăng ký
  • GETHạn mức hoá đơn
  • POSTTạo mẫu hoá đơn
  • POSTDuyệt số lượng hoá đơn
  • DELETEXoá mẫu chưa duyệt
  • POSTTạo hoá đơn
  • GETDanh sách hoá đơn
  • POSTKý hoá đơn nháp
  • GETTải hoá đơn PDF/XML
  • DELETEXoá hoá đơn nháp

Tra cứu

  • GETTra cứu mã số thuế

Webhook

  • GETDanh sách webhook
  • POSTThêm webhook
  • POSTNhận và kiểm tra
Trang chủTài liệuMã lỗi

Mã lỗi

Lỗi của hddt.dev trả mã HTTP và error.code. Lỗi nghiệp vụ khi tạo hoặc ký hoá đơn nằm ở success, error_code và message.

Markdown

#Giới thiệu

Đọc mã HTTP trước. 2xx là request được chấp nhận. 4xx là request của bạn cần sửa. 5xx là lỗi phía hddt.dev hoặc nhà cung cấp, thử lại sau.

Trang từng API liệt kê mã riêng của endpoint đó. Bảng dưới đây là các mã dùng chung.

#Thân lỗi

Lỗi xác thực, định dạng và giới hạn trả JSON có error.code và error.message. error.param chỉ có khi lỗi trỏ vào một trường.

401
{
  "error": {
    "code": "unauthorized",
    "message": "Thiếu xác thực."
  }
}

#Mã thường gặp

Cùng một mã HTTP có thể kèm câu message khác nhau. Dùng error.code để rẽ nhánh, dùng message để hiện cho người tích hợp.

HTTPMãKhi nào
400bad_requestJSON sai hoặc thiếu tham số bắt buộc.
401unauthorizedThiếu hoặc sai API key, token hết hạn, token không cùng ứng dụng với key, hoặc ứng dụng chưa cấu hình tài khoản nhà cung cấp khi lấy token.
402—Hết hạn mức hoá đơn của môi trường đang gọi.
403forbiddenKey không thuộc ứng dụng, key và host khác môi trường, ứng dụng đang tạm dừng, hoặc Live chưa được bật.
404not_foundKhông có ứng dụng, mẫu, hoá đơn, hoặc không có endpoint.
409conflictCùng Idempotency-Key nhưng nội dung khác, hoặc mã tham chiếu đã tồn tại theo chính sách đang gửi.
422validation_errorTrường có mặt nhưng giá trị không hợp lệ.
429rate_limitedVượt số request cho phép trong một phút.
500internal_errorLỗi nội bộ. Thử lại sau.
503provider_unavailableTra cứu mã số thuế không thực hiện được lúc này.

#Giới hạn request

Mỗi môi trường có một giới hạn request mỗi phút. Số này hiện trên tab Kết nối & bảo mật, dòng Giới hạn. Phản hồi có header X-RateLimit-Limit và X-RateLimit-Remaining.

Khi vượt giới hạn, API trả 429 rate_limited và header Retry-After là số giây còn lại trong phút hiện tại. Chờ hết khoảng đó rồi gửi lại. Không gửi dồn ngay.

#Lỗi nghiệp vụ hoá đơn

Tạo hoá đơn, ký hoá đơn và danh sách hoá đơn còn có dạng kết quả nghiệp vụ: success là false, error_code và message mô tả lý do từ quy trình hoá đơn. Đó không phải error.code ở mục Thân lỗi.

Lỗi xác thực, hết hạn mức và sai định dạng của hddt.dev vẫn trả mã HTTP trong bảng trên, kể cả khi gọi các API hoá đơn.

Không thử lại mọi lỗi

401 và 422 cần sửa request hoặc lấy token mới. 409 với cùng Idempotency-Key nghĩa là nội dung đã đổi, hãy dùng key mới. 429 chờ Retry-After. 5xx có thể gửi lại.
Trước đóMôi trường sandboxTiếp theoThông tin ứng dụng
Trang này có hữu ích không?
Cập nhật lần cuối: 16/11/2026

Trên trang này

  • Giới thiệu
  • Thân lỗi
  • Mã thường gặp
  • Giới hạn request
  • Lỗi nghiệp vụ hoá đơn
Đăng nhậpBắt đầu ngay