Exit code và mã lỗi SePay CLI

Tra exit code và error_code của SePay CLI khi lệnh báo lỗi, để biết lỗi do CLI hay server trả về, cách xử lý và có nên chạy lại lệnh hay không.

||

Lệnh SePay CLI chạy thành công trả exit code 0. Exit code khác 0 cho biết nhóm lỗi, error_code cho biết lỗi cụ thể.

Exit code

ExitÝ nghĩaXử lý
1Lỗi chung: server lỗi, lỗi mạng, dữ liệu bị từ chối, hết hạn mứcXem error_code.
2Sai tham số hoặc flag, lệnh con không tồn tại, lệnh chỉ dành cho sandbox chạy với --env production, cần xác nhận mà không có terminal, hoặc lệnh sửa dữ liệu trên production không đạt luật xác nhậnKiểm tra --help. Trên sandbox, thêm --yes nếu là xác nhận. Trên production, message có ask the user to run this command in their own terminal: người dùng tự chạy lệnh trong terminal của họ; agent không thêm --yes.
3Lệnh chưa được hỗ trợKhông thử lại. Lệnh chỉ chạy được khi một bản CLI mới hỗ trợ nó.
4Chưa đăng nhập hoặc token hết hạnsepay login.
5Token thiếu scope trên productionĐăng nhập lại và cấp scope đó cùng các scope đang có (Xác thực).
6Handler không phản hồi, hoặc trả status không phải 2xx (hay khác --expect-status); chỉ webhook test trả exit nàyKiểm tra handler, chạy lại.
8Công ty hoặc tài khoản chưa được bật tính năngTest mode: SuperAdmin, Admin hoặc người dùng có quyền Developer bật Test mode trên sidebar my.sepay.vn. Thiếu quyền: nhờ admin công ty cấp.
130Lệnh bị dừng giữa chừng: bạn bấm Ctrl+C, bấm Esc ở một câu hỏi, hoặc tiến trình nhận SIGINT, SIGTERM (ví dụ job CI bị hủy)Trong terminal, CLI không in gì thêm. Chạy lại khi sẵn sàng.

Exit 5 và 8 đều có thể đến từ HTTP 403: 5 bạn tự sửa được, 8 cần SePay hoặc admin công ty xử lý.

Exit 1 gồm cả lỗi tạm thời lẫn lỗi cố định: chỉ thử lại khi bảng error_code ghi Có (hoặc Tùy, sau khi đọc message), và giới hạn số lần thử. Exit 2, 3, 4, 5 và 8 sẽ lỗi y như cũ cho tới khi xử lý xong nguyên nhân.

Liên hệ SePay: sepay.vn/lien-he, gửi kèm email tài khoản, error_code và request_id nếu có.

error_code chi tiết

Khi request đã tới server, error_code là mã server trả về, CLI giữ nguyên. Khi lỗi xảy ra trên máy trước khi tới server, CLI tự đặt một trong các mã error, usage_error, not_implemented, unauthenticated, insufficient_scope, network_error, forward_failed, interrupted. Server trả HTTP 403 không kèm mã thì error_code là blocked; HTTP 5xx không kèm mã thì là server_error.

Các mã khác trong bảng, như idempotency_conflict, vcb_cancel_not_allowed, insufficient_role, đến từ server và có thể thay đổi theo server. Gặp mã CLI chưa biết thì đọc message: đó là nguyên văn thông báo của server.

error_codeExitÝ nghĩaXử lýCó thể thử lại?
validation_error1Dữ liệu gửi lên bị từ chốiSửa trường errors trong JSON.Không
quota_exceeded1Hết hạn mức (ví dụ 500 giao dịch/ngày)Đợi reset (00:00 VN) hoặc tăng hạn mức.Không
rate_limited1Gọi quá nhiều requestCLI đã tự đợi theo Retry-After và thử lại trước khi báo lỗi. Đợi thêm rồi thử lại, giảm tần suất.Có
idempotency_conflict1Lệnh trước cùng --idempotency-key chưa kết thúc: đang chạy, hoặc đã dừng giữa chừngKiểm tra bản ghi đã được tạo chưa (ví dụ webhook list). Chưa có thì chạy lại cùng key sau; key được mở lại sau tối đa 1 giờ.Có
idempotency_key_reuse1--idempotency-key đã được dùng cho một request khác (flag hoặc nội dung khác lần trước)Dùng key mới.Không
error1Lỗi chung, server không kèm mã cụ thể hơnĐọc message. Với bankhub link-token get và pg order get, đây có thể là không tìm thấy bản ghi: đừng thử lại.Tùy
network_error1Không nhận được phản hồi dùng được từ SePay: mất kết nối, lỗi DNS, kết nối bị từ chối hoặc bị ngắt, hết thời gian chờ, chứng chỉ không tin cậyKiểm tra kết nối mạng rồi chạy lại; lệnh tạo dữ liệu thì giữ nguyên --idempotency-key.Có
server_error1SePay lỗi phía server (HTTP 5xx) và không kèm mã. message là SePay is temporarily unavailable (HTTP 503); retry in a moment (tương tự với 502, 504) hoặc SePay had an internal error (HTTP 500); retry in a moment, ...Chờ một lúc rồi chạy lại. Lỗi lặp lại thì gửi SePay request_id (có trong message và trong JSON lỗi).Có
*_provision_failed, bankhub_token_failed, einvoice_token_failed1Sandbox chưa sẵn sàngThử lại.Có
product_token_failed1SePay không cấp được thông tin xác thực của sản phẩm (pg, einvoice, bankhub)Thử lại, sau đó báo SePay.Có
live_company_unresolved1SePay không xác định được công ty của bạn cho request nàysepay login.Không
sms_not_allowed1Gói dịch vụ không bao gồm kết nối SMSDùng --connection api.Không
connection_not_supported1Ngân hàng không có kết nối APIChọn ngân hàng khác, hoặc dùng --connection sms nếu gói có SMS.Không
not_found1Endpoint chỉ có trên sandbox, không phải thiếu bản ghi; thông báo của server (in nguyên văn) nói cách xử lýChạy lại trên sandbox.Không
4041Bank Hub không tìm thấy bản ghi; message là not found, or not visible to this merchantKiểm tra xid và --env: sandbox và production là hai bộ dữ liệu riêng.Không
EINVOICE_DOCUMENT_NOT_FOUND1Không có hóa đơn với reference_code nàyKiểm tra mã và --env.Không
EINVOICE_ACCOUNT_NOT_FOUND1Công ty chưa có tài khoản nhà cung cấp hóa đơn điện tửXem Hóa đơn điện tử.Không
4000, 4001, 40021pg order void bị từ chối: đơn chưa thanh toán, đã hủy, hoặc không có giao dịchXem đơn bằng pg order get (Cổng thanh toán).Không
replay_not_dispatched1webhook replay bị từ chối, không có gì được gửi; lý do của server in sau Reason:Đọc lý do, xử lý rồi mới chạy lại.Không
replay_already_delivered1webhook replay trên production: handler đã nhận thành công lần gửi gần nhất tới webhook nàyKiểm tra đơn hàng trước. Vẫn cần gửi lại thì thêm --force và gõ lại mã giao dịch khi CLI hỏi.Không
replay_rate_limited1webhook replay trên production: giao dịch đã chạm giới hạn số lần gửi lại (tính chung mọi webhook của giao dịch). CLI không tự thử lạiĐợi tới thời điểm thông báo ghi rồi chạy lại.Tùy
replay_busy1Một lần gửi lại khác của cùng giao dịch đang chạyĐợi vài giây rồi chạy lại.Có
paycode_prefix_exists1paycode create dùng tiền tố công ty đã có (không phân biệt hoa thường)Sửa cấu trúc đó bằng sepay paycode update --structure <prefix>, hoặc chọn tiền tố khác.Không
paycode_version_conflict1Cấu hình mã thanh toán đã đổi kể từ lúc lệnh đọc nó; chưa có gì được lưuChạy lại lệnh; nếu bạn tự truyền --idempotency-key thì dùng key mới.Có
multiple_companies1Tài khoản thuộc nhiều công tySử dụng tài khoản một công ty duy nhất.Không
unsupported_api_version1CLI quá cũCập nhật CLI.Không
vcb_cancel_not_allowed1Đơn hàng hoặc VA đang ở trạng thái không hủy được (chỉ gặp qua sepay api)Xem trạng thái hiện tại của đơn trước khi hủy.Không
usage_error2Sai tham số hoặc flag, lệnh con không tồn tại, cần xác nhận mà không có terminal, hoặc lệnh sửa dữ liệu trên production không đạt luật xác nhậnKiểm tra --help. Sandbox: thêm --yes nếu là xác nhận. Production: người dùng tự chạy lệnh trong terminal của họ.Không
not_implemented3Lệnh chưa được hỗ trợKhông thử lại.Không
forward_failed6Handler không nhận thông báo do webhook test gửiSửa handler rồi chạy lại. webhook test in kết quả riêng ra stdout ("ok": false) thay cho đối tượng lỗi JSON.Có, sau khi sửa
unauthenticated, unauthorized4Chưa đăng nhập hoặc token không hợp lệsepay login.Không
access_revoked4Phiên đăng nhập bị thu hồi, webhook listen dừngsepay login rồi chạy lại lệnh.Không
insufficient_scope5Token thiếu scopeĐăng nhập lại, cấp scope đó cùng các scope đang có.Không
test_mode_disabled8Công ty chưa được bật Test modeBật Test mode trên sidebar my.sepay.vn (Test mode).Không
sandbox_not_provisioned8Công ty chưa có môi trường sandboxLiên hệ SePay để được cấp.Không
sse_hub_disabled8SePay đang tắt luồng stream; gặp ở các lệnh listen và webhook testLiên hệ SePay.Không
forbidden, insufficient_role8Không đủ vai trò hoặc quyềnNhờ admin công ty cấp quyền.Không
blocked8HTTP 403 không kèm mã cụ thể hơnLiên hệ SePay hoặc admin công ty.Không
interrupted130Bạn bấm Ctrl+C hoặc Esc, hoặc lệnh nhận SIGINT, SIGTERMChạy lại khi sẵn sàng; lệnh tạo dữ liệu thì giữ nguyên --idempotency-key.Có

Định dạng lỗi JSON (--json)

Với --json, lỗi in ra stderr như sau:

JSON
1
2
3
4
5
6
{
"status": "error",
"error_code": "forbidden",
"message": "your account lacks permission for this action; ask an admin of your company",
"exit_code": 8
}

status luôn là error. error_code là mã chi tiết trong bảng error_code và exit_code là số exit code. message bằng tiếng Anh nếu CLI biết mã lỗi; nếu không, đó là nguyên văn thông báo của server (có thể bằng tiếng Việt). Khi error_code là validation_error, JSON có thêm errors: tên trường bị từ chối và lý do. Khi server trả mã request, JSON có thêm request_id; gửi mã này cho SePay khi báo lỗi HTTP 5xx.

Ví dụ, tạo webhook tắt nhận giao dịch của số tài khoản chính (off) trên một tài khoản chưa có VA nào:

$ sepay webhook create --url https://example.com/hook --bank-mode single \  --bank-account <bank-account-xid> --bank-config <bank-account-xid>=off:all --json{"status": "error","error_code": "validation_error","message": "the request failed validation","exit_code": 1,"errors": {  "bank_config": "bank account <bank-account-xid> has no virtual accounts; receive_primary must be true"}}

Không có --json thì lỗi in dạng Error: the request failed validation, kèm một dòng - bank_config: ... cho mỗi trường bị từ chối.

Lệnh login và auth có thể báo OAuth error "unknown_error": máy chủ OAuth trả lỗi mà không kèm mã. unknown_error chỉ nằm trong message; error_code khi đó là error.

Cách xử lý tự động trong script: Script.