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ĩa | Xử lý |
|---|---|---|
1 | Lỗi chung: server lỗi, lỗi mạng, dữ liệu bị từ chối, hết hạn mức | Xem error_code. |
2 | Sai 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ận | Kiể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. |
3 | Lệ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ó. |
4 | Chưa đăng nhập hoặc token hết hạn | sepay login. |
5 | Token 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). |
6 | Handler 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ày | Kiểm tra handler, chạy lại. |
8 | Công ty hoặc tài khoản chưa được bật tính năng | Test 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. |
130 | Lệ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_code | Exit | Ý nghĩa | Xử lý | Có thể thử lại? |
|---|---|---|---|---|
validation_error | 1 | Dữ liệu gửi lên bị từ chối | Sửa trường errors trong JSON. | Không |
quota_exceeded | 1 | Hế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_limited | 1 | Gọi quá nhiều request | CLI đã 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_conflict | 1 | Lệnh trước cùng --idempotency-key chưa kết thúc: đang chạy, hoặc đã dừng giữa chừng | Kiể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_reuse | 1 | --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 |
error | 1 | Lỗ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_error | 1 | Khô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ậy | Kiể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_error | 1 | SePay 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_failed | 1 | Sandbox chưa sẵn sàng | Thử lại. | Có |
product_token_failed | 1 | SePay 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_unresolved | 1 | SePay không xác định được công ty của bạn cho request này | sepay login. | Không |
sms_not_allowed | 1 | Gói dịch vụ không bao gồm kết nối SMS | Dùng --connection api. | Không |
connection_not_supported | 1 | Ngân hàng không có kết nối API | Chọn ngân hàng khác, hoặc dùng --connection sms nếu gói có SMS. | Không |
not_found | 1 | Endpoint 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 |
404 | 1 | Bank Hub không tìm thấy bản ghi; message là not found, or not visible to this merchant | Kiểm tra xid và --env: sandbox và production là hai bộ dữ liệu riêng. | Không |
EINVOICE_DOCUMENT_NOT_FOUND | 1 | Không có hóa đơn với reference_code này | Kiểm tra mã và --env. | Không |
EINVOICE_ACCOUNT_NOT_FOUND | 1 | Cô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, 4002 | 1 | pg order void bị từ chối: đơn chưa thanh toán, đã hủy, hoặc không có giao dịch | Xem đơn bằng pg order get (Cổng thanh toán). | Không |
replay_not_dispatched | 1 | webhook 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_delivered | 1 | webhook replay trên production: handler đã nhận thành công lần gửi gần nhất tới webhook này | Kiể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_limited | 1 | webhook 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_busy | 1 | Mộ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_exists | 1 | paycode 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_conflict | 1 | Cấu hình mã thanh toán đã đổi kể từ lúc lệnh đọc nó; chưa có gì được lưu | Chạy lại lệnh; nếu bạn tự truyền --idempotency-key thì dùng key mới. | Có |
multiple_companies | 1 | Tài khoản thuộc nhiều công ty | Sử dụng tài khoản một công ty duy nhất. | Không |
unsupported_api_version | 1 | CLI quá cũ | Cập nhật CLI. | Không |
vcb_cancel_not_allowed | 1 | Đơ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_error | 2 | Sai 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ận | Kiể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_implemented | 3 | Lệnh chưa được hỗ trợ | Không thử lại. | Không |
forward_failed | 6 | Handler không nhận thông báo do webhook test gửi | Sử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, unauthorized | 4 | Chưa đăng nhập hoặc token không hợp lệ | sepay login. | Không |
access_revoked | 4 | Phiên đăng nhập bị thu hồi, webhook listen dừng | sepay login rồi chạy lại lệnh. | Không |
insufficient_scope | 5 | Token thiếu scope | Đăng nhập lại, cấp scope đó cùng các scope đang có. | Không |
test_mode_disabled | 8 | Công ty chưa được bật Test mode | Bật Test mode trên sidebar my.sepay.vn (Test mode). | Không |
sandbox_not_provisioned | 8 | Công ty chưa có môi trường sandbox | Liên hệ SePay để được cấp. | Không |
sse_hub_disabled | 8 | SePay đang tắt luồng stream; gặp ở các lệnh listen và webhook test | Liên hệ SePay. | Không |
forbidden, insufficient_role | 8 | Không đủ vai trò hoặc quyền | Nhờ admin công ty cấp quyền. | Không |
blocked | 8 | HTTP 403 không kèm mã cụ thể hơn | Liên hệ SePay hoặc admin công ty. | Không |
interrupted | 130 | Bạn bấm Ctrl+C hoặc Esc, hoặc lệnh nhận SIGINT, SIGTERM | Chạ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:
{"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.