Mã lỗi

Khung lỗi chung của Open API và bảng mã lỗi kèm việc cần làm cho từng mã.

Mọi lỗi dưới /api/open/ có cùng một khung.

{
  "error": {
    "code": "invoice.external_id_conflict",
    "message": "Mã giao dịch external_id đã dùng cho một hóa đơn khác (nội dung gửi khác lần trước).",
    "details": { "external_id": "CN5-P03-V2-20261022-000123" }
  },
  "request_id": "7a1f0c2e-5b0d-4d0c-a0c4-3f3e6c9d9b10"
}

Trường	Kiểu	Ý nghĩa
`error.code`	chuỗi	Mã lỗi ổn định, dùng để xử lý trong chương trình. Bảng mã ở dưới
`error.message`	chuỗi	Câu tiếng Việt cho người đọc, có thể đổi chữ
`error.details`	đối tượng hoặc `null`	Thông tin thêm theo từng mã, ví dụ `external_id`, `scope`, `errors`
`request_id`	chuỗi	Mã tra cứu request. Gửi kèm khi cần NexERP hỗ trợ

Dựa vào error.code để xử lý trong chương trình. message là câu tiếng Việt cho người đọc, có thể đổi chữ.
Lỗi 422 request.invalid có error.details.errors: danh sách {loc, type, msg} chỉ ra trường nào sai.
Gặp lỗi 5xx hoặc cần hỗ trợ thì gửi kèm request_id.

Bảng mã lỗi

Cột "Việc cần làm": Sửa là request sai, gửi lại y hệt sẽ lại lỗi. Thử lại là gửi lại y hệt sau một lúc. Báo là việc ở phía doanh nghiệp hoặc NexERP, hãy liên hệ họ.

Mã	HTTP	Ý nghĩa	Việc cần làm
`auth.missing_key`	401	Thiếu header `X-Api-Key`	Sửa: thêm header
`auth.invalid_key`	401	Khóa không đúng, hoặc khóa của môi trường khác	Sửa: kiểm tra khóa và địa chỉ gốc
`auth.key_revoked`	401	Khóa đã bị thu hồi	Báo: xin khóa mới
`auth.key_expired`	401	Khóa đã hết hạn	Báo: xin khóa mới
`auth.unauthorized`	401	Chưa xác thực, lỗi chung	Sửa: kiểm tra khóa
`auth.grant_inactive`	403	Doanh nghiệp đã tạm ngưng hoặc thu hồi quyền tích hợp	Báo: liên hệ doanh nghiệp
`auth.app_inactive`	403	Ứng dụng của bạn chưa được duyệt hoặc đang tạm ngưng	Báo: liên hệ NexERP
`auth.scope_missing`	403	Khóa không có phạm vi cần cho endpoint này (`error.details.scope`)	Báo: xin thêm phạm vi
`auth.forbidden`	403	Không có quyền, lỗi chung	Báo
`store.required`	403	Doanh nghiệp có nhiều cửa hàng mà thiếu `store_code`	Sửa: gửi `store_code`
`store.not_allowed`	403	Cửa hàng lạ, khóa không được dùng cửa hàng đó, hoặc cửa hàng chưa cấu hình đủ	Sửa mã cửa hàng. Vẫn lỗi thì Báo
`store.connection_not_mtt`	422	Kết nối hóa đơn điện tử của cửa hàng không phải loại khởi tạo từ máy tính tiền, hoặc đã ngừng	Báo: doanh nghiệp hoặc NexERP cấu hình lại
`request.invalid`	422	Dữ liệu sai quy tắc: thiếu trường, sai kiểu, quá dài, trường lạ, `issued_at` thiếu múi giờ	Sửa: xem `details.errors`
`line.quantity_must_be_string`	422	`quantity` gửi dạng số JSON	Sửa: gửi dạng chuỗi, ví dụ `"3.742515"`
`line.amount_anchor_mismatch`	422	Dòng KKKNT, KCT, 0: `quantity × unit_price` làm tròn không bằng `amount`	Sửa số lượng hoặc bỏ trống `quantity`
`line.amount_anchor_scale`	422	Đơn giá từ 1.000.000 đồng trở lên mà số lượng có phần lẻ	Sửa: dùng số lượng nguyên
`line.amount_anchor_taxable_unsupported`	422	Dòng thuế 5, 8, 10: thiếu `quantity`, quá 4 chữ số lẻ, hoặc `quantity × unit_price` khác `amount`	Sửa
`buyer.name_required`	422	Có mã số thuế người mua mà doanh nghiệp chưa có khách này, và thiếu `buyer.name`	Sửa: gửi tên
`buyer.name_incomplete`	422	Có `citizen_id` nhưng `buyer.name` không phải họ tên đầy đủ	Sửa: gửi họ tên đủ, hoặc bỏ `citizen_id`
`buyer.tax_code_invalid`	422	Mã số thuế không đúng dạng 10, 12 hoặc 13 chữ số	Sửa
`invoice.issued_at_in_future`	422	`issued_at` ở tương lai quá 5 phút	Sửa đồng hồ máy bán hàng
`invoice.too_old`	422	`issued_at` cũ hơn số ngày cho phép của ứng dụng, mặc định 3	Báo: nhờ kế toán lập tay
`invoice.period_locked`	409	Kỳ thuế GTGT của ngày hóa đơn đã nộp tờ khai	Báo: doanh nghiệp xử lý, rồi gửi lại
`invoice.external_id_conflict`	409	`external_id` đã dùng với nội dung khác	Sửa: giao dịch mới thì dùng `external_id` mới. Gửi lại giao dịch cũ thì gửi đúng nội dung cũ
`invoice.not_found`	404	Không có hóa đơn này của ứng dụng bạn, kể cả hóa đơn của người khác	Sửa: kiểm tra `id` hoặc `external_id`
`invoice.replace_journal_unsupported`	422	Thay thế chỉ dùng khi `journal_mode = none`, hoặc hóa đơn gốc đã ghi sổ	Báo
`invoice.replace_not_allowed`	409	Hóa đơn gốc chưa phát hành, đã hủy hoặc đã thay thế, hoặc lần thay thế trước thất bại	Chờ phát hành xong, hoặc Báo để kế toán hủy bản thất bại
`invoice.replace_store_mismatch`	422	Hóa đơn thay thế khác cửa hàng với hóa đơn gốc	Sửa `store_code`
`log.liters_must_be_string`	422	`liters` gửi dạng số JSON	Sửa: gửi dạng chuỗi, ví dụ `"4.627"`
`log.amount_mismatch`	422	`liters × unit_price` lệch `amount` quá 1 %	Sửa: kiểm tra các trường bị đảo
`log.fuel_code_unknown`	422	Mã nhiên liệu chưa có trong danh mục doanh nghiệp khai	Báo: doanh nghiệp khai thêm, rồi gửi lại
`log.pumped_at_in_future`	422	`pumped_at` ở tương lai quá 5 phút	Sửa đồng hồ máy trụ bơm
`log.too_old`	422	`pumped_at` cũ hơn số ngày cho phép (mặc định 3)	Báo: nhờ kế toán lập tay
`log.id_conflict`	409	`id_log` đã dùng với nội dung khác, hoặc đã là `external_id` của một hóa đơn	Sửa: giao dịch mới thì dùng `id_log` mới
`log.duplicate_in_batch`	422	Chỉ trong kết quả lô: `id_log` trùng một phần tử trước trong cùng lô	Sửa: bỏ phần tử trùng
`log.not_found`	404	Không có giao dịch bơm này của ứng dụng bạn	Sửa: kiểm tra `id_log`
`request.too_many_logs`	413	Lô hơn 100 giao dịch	Sửa: chia nhỏ lô
`einvoice.link_not_ready`	409	Hóa đơn điện tử chưa phát hành, chưa có link	Thử lại khi `einvoice_status` là `issued`
`einvoice.link_unavailable`	502	Nhà cung cấp không trả được link	Thử lại sau
`rate_limited`	429	Gọi quá nhanh, hoặc nhà cung cấp hóa đơn điện tử đang bận khi lấy link	Thử lại sau `Retry-After` giây
`request.bad`	400	Yêu cầu không hợp lệ, lỗi chung	Sửa
`not_found`	404	Đường dẫn không tồn tại, hoặc cổng đang tắt	Sửa địa chỉ. Cổng tắt thì Báo
`method_not_allowed`	405	Sai phương thức HTTP	Sửa
`conflict`	409	Dữ liệu xung đột, lỗi chung	Đọc `message`
`request.too_large`	413	Thân gửi lên quá lớn	Sửa: giảm số dòng
`request.unsupported_media_type`	415	`Content-Type` không phải JSON	Sửa: `application/json`
`internal_error`	500	Lỗi máy chủ	Thử lại. Còn lỗi thì Báo kèm `request_id`
`upstream_error`	502	Hệ thống phía sau lỗi	Thử lại
`service.unavailable`	503	Cổng tạm thời chưa sẵn sàng	Thử lại sau
`upstream_timeout`	504	Hệ thống phía sau không trả lời kịp	Thử lại. `POST /invoices` gửi lại an toàn nhờ `external_id`

Mã HTTP chưa có trong bảng ra mã dạng http_<số>.

Lưu ý

Có thể gặp mã không có trong bảng, ví dụ lỗi nghiệp vụ mới thêm. Xử lý theo mã HTTP: 4xx là sửa dữ liệu hoặc chờ, 5xx là thử lại.
Lỗi mạng, timeout, 429 và 5xx thì thử lại y hệt, có chờ và tăng dần. 4xx còn lại thì không thử lại nguyên văn.