# Mã lỗi > Chỉ dùng endpoint, field, mã lỗi và ví dụ trong trang này. Không thêm API chưa được mô tả ở đây. 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. ## 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: ```json { "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. | HTTP | Mã | Khi nào | | --- | --- | --- | | `400` | `bad_request` | JSON sai hoặc thiếu tham số bắt buộc. | | `401` | `unauthorized` | Thiế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. | | `403` | `forbidden` | Key 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. | | `404` | `not_found` | Không có ứng dụng, mẫu, hoá đơn, hoặc không có endpoint. | | `409` | `conflict` | Cù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. | | `422` | `validation_error` | Trường có mặt nhưng giá trị không hợp lệ. | | `429` | `rate_limited` | Vượt số request cho phép trong một phút. | | `500` | `internal_error` | Lỗi nội bộ. Thử lại sau. | | `503` | `provider_unavailable` | Tra 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. Trang HTML: /docs/errors Cập nhật: 16/11/2026