Xử lý lỗi khi tích hợp eInvoice API

Trang này tập hợp toàn bộ thông tin về lỗi của eInvoice API: cấu trúc response lỗi, ý nghĩa từng mã lỗi, cơ chế retry tự động và cách xử lý khi hóa đơn không được phát hành.

Hai loại lỗi

Cấu trúc response lỗi

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

{
  "success": false,
  "error": {
    "code": "EINVOICE_DOCUMENT_EXISTED",
    "message": "Hệ thống đã ghi nhận hoá đơn cho mã tham chiếu này."
  }
}

Xử lý lỗi dựa trên error.code, không khớp theo chuỗi error.message. message là văn bản tiếng Việt dùng để hiển thị hoặc ghi log, nội dung có thể thay đổi.

Phân loại lỗi

Lỗi HTTP

Mã lỗi thường gặp

QUOTA_HAS_BEEN_USERD_UP viết đúng như API trả về, kể cả lỗi chính tả trong mã.

Mỗi endpoint còn có bảng Xử lý lỗi riêng, liệt kê đầy đủ mã lỗi của endpoint đó, ví dụ Xuất hóa đơn và Phát hành hóa đơn.

Lịch retry

API tạo và phát hành hóa đơn chạy bất đồng bộ: response trả về tracking_code, phần xử lý còn lại chạy nền. Khi phần chạy nền gặp lỗi tạm thời, SePay tự thử lại với khoảng cách giữa các lần tăng dần theo Fibonacci:

Tổng cộng 8 lần xử lý (1 lần đầu cộng 7 lần retry), kéo dài khoảng 33 phút nếu tất cả đều thất bại.

Ngoài số lần, còn một giới hạn thứ hai: yêu cầu tạo quá 2 giờ sẽ không được retry nữa, kể cả khi chưa dùng hết 8 lần. Đây là vùng an toàn dự phòng cho trường hợp một lần xử lý bị treo. Thông thường không chạm tới giới hạn này vì chuỗi 33 phút đã kết thúc trước đó.

Chỉ lỗi hạ tầng được retry: nhà cung cấp hóa đơn trả 5xx, timeout, mất kết nối, hoặc lần xử lý bị ngắt giữa chừng. Lỗi do dữ liệu hoặc do trạng thái tài khoản luôn cho cùng một kết quả ở mọi lần thử, nên hệ thống trả Failed ngay.

Khối retry trong response trạng thái

Khi status là Pending và request đã gặp lỗi tạm thời ít nhất một lần, hai API theo dõi trạng thái trả thêm khối retry:

{
  "status": "Pending",
  "retry": {
    "retries_count": 2,
    "max_retries": 7,
    "next_retry_at": "2026-09-04 15:12:30"
  }
}

Hai điểm dễ hiểu nhầm:

• Không có khối retry: request chưa gặp lỗi lần nào và đang chờ xử lý lần đầu, không phải retry đã bị tắt.
• next_retry_at là null: không còn lần retry nào được lên lịch, do đã hết 7 lần hoặc quá 2 giờ, và hệ thống đang chốt kết quả cuối cùng. Không phải sắp retry ngay.

Chẩn đoán khi hóa đơn không được phát hành

Kiểm tra lần lượt theo thứ tự dưới đây. Nguyên nhân thường nằm ở các bước đầu.

1. Kiểm tra response

success: false là lỗi đồng bộ, đọc error.code theo các bảng ở trên. success: true kèm data.tracking_code nghĩa là yêu cầu đã được tiếp nhận, chuyển sang bước 2.

2. Kiểm tra môi trường

Production là https://einvoice-api.sepay.vn, Sandbox là https://einvoice-api-sandbox.sepay.vn. Token chỉ dùng được cho môi trường đã cấp nó, gửi token Sandbox tới Production sẽ nhận 401. Xem Sandbox.

3. Kiểm tra hạn token

Token có hiệu lực 24 giờ. Tiến trình chạy dài dùng lại token đã cache từ hôm trước sẽ nhận 401 TOKEN_EXPIRED giữa chừng. Lấy token mới khi gặp 401, không cần lấy lại ở mỗi request.

4. Kiểm tra status

Gọi Trạng thái xuất hóa đơn hoặc Trạng thái phát hành với tracking_code.

5. Hóa đơn đang ở dạng nháp

Gửi is_draft: true khi tạo thì hóa đơn dừng ở dạng nháp, chưa gửi lên Cơ quan Thuế và không tính vào hạn mức. Cần gọi thêm Phát hành hóa đơn để phát hành.

6. Kiểm tra hạn mức

Khi hết hạn mức, mọi yêu cầu phát hành đều trả Failed với cùng một lý do. Gọi API kiểm tra hạn mức để xem số lượt còn lại.

7. Kiểm tra phê duyệt của Cơ quan Thuế

Khi tờ khai chưa được duyệt, không hóa đơn nào phát hành được. Xem tax_authority_approved_date trong Danh sách tài khoản nhà cung cấp. Ngày hóa đơn cũng phải từ ngày này trở đi.

Trước khi gửi lại

Failed không đồng nghĩa với việc chưa có hóa đơn nào được tạo. Kiểm tra trước khi gửi lại:

1. Gọi Chi tiết hóa đơn với reference_code của bạn.
2. Trả về 404: chưa có hóa đơn nào được ghi nhận, có thể gửi lại.
3. Trả về dữ liệu hóa đơn: hóa đơn đã tồn tại, không gửi lại. Xem status trong response để biết hóa đơn cần phát hành tiếp hay đã hoàn tất.

API Xuất hóa đơn chặn sẵn trường hợp này: gửi lại cùng một reference_code mà hệ thống đã ghi nhận hóa đơn sẽ trả 409 EINVOICE_DOCUMENT_EXISTED. Đây là lớp bảo vệ có sẵn, không dùng thay cho bước kiểm tra ở trên. Mỗi hóa đơn cần một reference_code duy nhất do bạn sinh ra, và khi gửi lại phải dùng đúng mã đó.

Câu hỏi thường gặp

Tiếp theo

• Trạng thái xuất hóa đơn: chi tiết response của API theo dõi
• Trạng thái phát hành: chi tiết response của API theo dõi
• Chi tiết hóa đơn: tra hóa đơn theo reference_code
• Kiểm tra hạn mức: số lượt phát hành còn lại
• Sandbox: môi trường thử nghiệm trước khi chạy thật