A SePay CLI command that succeeds exits with code 0. A non-zero exit code tells you the kind of failure; error_code tells you the exact error.
Exit codes
| Exit | Meaning | Action |
|---|---|---|
1 | General error: server error, network error, data rejected, quota exceeded | See error_code. |
2 | A wrong argument or flag, an unknown subcommand, a sandbox-only command run with --env production, a confirmation needed without a terminal, or a command that changes data on production that doesn't meet the confirmation rule | Check --help. On sandbox, add --yes if it's a confirmation. On production, message contains ask the user to run this command in their own terminal: the user runs the command in their own terminal; an agent doesn't add --yes. |
3 | The command isn't supported yet | Don't retry. It runs only once a new CLI release supports it. |
4 | Not signed in, or the token has expired | sepay login. |
5 | The token lacks a scope on production | Sign in again and grant the scope together with the ones you already have (Authentication). |
6 | The handler didn't respond, or answered with a non-2xx status (or one other than --expect-status); only webhook test returns it | Check your handler and run again. |
8 | The company or account doesn't have the feature enabled | Test mode: a SuperAdmin, an Admin or a user with the Developer permission turns on Test mode in the my.sepay.vn sidebar. Missing permission: ask your company admin. |
130 | The command was stopped part-way: you pressed Ctrl+C, pressed Esc at a prompt, or the process got SIGINT or SIGTERM (a cancelled CI job, for example) | In a terminal, the CLI prints nothing more. Run it again when ready. |
Exit 5 and 8 can both come from an HTTP 403: you fix 5 yourself, while 8 needs SePay or your company admin to act.
Exit 1 covers both temporary and permanent errors: retry only when the error_code table says Yes (or Depends, after reading message), and cap the number of retries. Exits 2, 3, 4, 5 and 8 fail the same way until the cause is fixed.
Contact SePay: sepay.vn/lien-he, with your account email, the error_code and the request_id if there is one.
error_code details
When a request reached the server, error_code is the server's code, passed through unchanged. When the failure happens locally before any request, the CLI sets one of error, usage_error, not_implemented, unauthenticated, insufficient_scope, network_error, forward_failed, interrupted. An HTTP 403 from the server with no code gives blocked; an HTTP 5xx with no code gives server_error.
The other codes in the table, such as idempotency_conflict, vcb_cancel_not_allowed and insufficient_role, come from the server and can change with it. For a code the CLI doesn't know, read message: it is the server's message as is.
error_code | Exit | Meaning | Action | Retryable? |
|---|---|---|---|---|
validation_error | 1 | The submitted data was rejected | Fix the fields listed in errors in the JSON. | No |
quota_exceeded | 1 | Quota exceeded (for example 500 transactions/day) | Wait for the reset (00:00 Vietnam time) or raise the quota. | No |
rate_limited | 1 | Too many requests | The CLI already waited per Retry-After and retried before failing. Wait longer, retry, and call less often. | Yes |
idempotency_conflict | 1 | An earlier command with the same --idempotency-key has not finished: it is still running, or it stopped midway | Check whether the record was created (for example webhook list). If not, rerun with the same key later; the key is released after at most 1 hour. | Yes |
idempotency_key_reuse | 1 | The --idempotency-key was already used for a different request (other flags or body) | Use a new key. | No |
error | 1 | General error; the server sent no more specific code | Read message. With bankhub link-token get and pg order get it can mean the record wasn't found: don't retry. | Depends |
network_error | 1 | No usable answer came back from SePay: no connection, DNS failure, refused or cut connection, timeout, untrusted certificate | Check the network connection and run it again; for a command that creates data, keep the same --idempotency-key. | Yes |
server_error | 1 | SePay failed on its side (HTTP 5xx) without a code. message is SePay is temporarily unavailable (HTTP 503); retry in a moment (likewise for 502 and 504) or SePay had an internal error (HTTP 500); retry in a moment, ... | Wait a moment and run it again. If it keeps failing, send SePay the request_id (in message and in the JSON error). | Yes |
*_provision_failed, bankhub_token_failed, einvoice_token_failed | 1 | The sandbox isn't ready yet | Retry. | Yes |
product_token_failed | 1 | SePay couldn't issue the product credential (pg, einvoice, bankhub) | Retry, then report it to SePay. | Yes |
live_company_unresolved | 1 | SePay couldn't resolve your company for the request | sepay login. | No |
sms_not_allowed | 1 | Your plan doesn't include SMS connections | Use --connection api. | No |
connection_not_supported | 1 | The bank has no API connection | Pick another bank, or use --connection sms if your plan includes SMS. | No |
not_found | 1 | The endpoint exists only on sandbox; it isn't a missing record. The server's message, printed as is, says what to do | Run it on sandbox. | No |
404 | 1 | Bank Hub couldn't find the record; message is not found, or not visible to this merchant | Check the xid and --env: sandbox and production hold separate data. | No |
EINVOICE_DOCUMENT_NOT_FOUND | 1 | No invoice has this reference_code | Check the code and --env. | No |
EINVOICE_ACCOUNT_NOT_FOUND | 1 | The company has no e-invoice provider account | See eInvoice. | No |
4000, 4001, 4002 | 1 | pg order void was refused: the order is unpaid, already cancelled, or has no transaction | Check the order with pg order get (Payment Gateway). | No |
replay_not_dispatched | 1 | webhook replay was refused and nothing was sent; the server's reason follows Reason: | Read the reason and fix it before running again. | No |
replay_already_delivered | 1 | Production webhook replay: your handler already acknowledged the last delivery to this webhook | Check the order first. If you still need to re-send it, add --force and type the transaction id back when asked. | No |
replay_rate_limited | 1 | Production webhook replay: the transaction reached its replay cap, counted across all its webhooks. The CLI doesn't retry it | Wait until the time the message gives, then run again. | Depends |
replay_busy | 1 | Another replay of the same transaction is still running | Wait a few seconds, then run again. | Yes |
paycode_prefix_exists | 1 | paycode create used a prefix the company already has (letter case aside) | Edit that structure with sepay paycode update --structure <prefix>, or pick another prefix. | No |
paycode_version_conflict | 1 | The payment code configuration changed after the command read it; nothing was saved | Run the command again; if you passed --idempotency-key, use a new key. | Yes |
multiple_companies | 1 | The account belongs to several companies | Use an account that belongs to a single company. | No |
unsupported_api_version | 1 | The CLI is too old | Update the CLI. | No |
vcb_cancel_not_allowed | 1 | The order or VA can't be cancelled in its current state (sepay api only) | Read the order's current state before cancelling. | No |
usage_error | 2 | A wrong argument or flag, an unknown subcommand, a confirmation needed without a terminal, or a command that changes data on production that doesn't meet the confirmation rule | Check --help. Sandbox: add --yes if it's a confirmation. Production: the user runs the command in their own terminal. | No |
not_implemented | 3 | The command isn't supported yet | Don't retry. | No |
forward_failed | 6 | The handler didn't accept the notification sent by webhook test | Fix the handler and run again. webhook test prints its own result to stdout ("ok": false) instead of the JSON error object. | Yes, after the fix |
unauthenticated, unauthorized | 4 | Not signed in, or the token is invalid | sepay login. | No |
access_revoked | 4 | Your sign-in session was revoked, so webhook listen stopped | sepay login, then run the command again. | No |
insufficient_scope | 5 | The token lacks a scope | Sign in again and grant the scope together with the ones you already have. | No |
test_mode_disabled | 8 | Test mode isn't enabled for the company | A SuperAdmin, an Admin or a user with the Developer permission turns on Test mode in the my.sepay.vn sidebar (Test mode). | No |
sandbox_not_provisioned | 8 | The company has no sandbox environment yet | Ask SePay to provision it. | No |
sse_hub_disabled | 8 | Streaming is turned off on SePay's side; seen on the listen commands and webhook test | Contact SePay. | No |
forbidden, insufficient_role | 8 | Insufficient role or permission | Ask your company admin to grant the permission. | No |
blocked | 8 | An HTTP 403 without a more specific code | Ask SePay or your company admin. | No |
interrupted | 130 | You pressed Ctrl+C or Esc, or the command got SIGINT or SIGTERM | Run it again when ready; for a command that creates data, keep the same --idempotency-key. | Yes |
JSON error format (--json)
With --json, errors are printed to stderr in this form:
{"status": "error","error_code": "forbidden","message": "your account lacks permission for this action; ask an admin of your company","exit_code": 8}
status is always error. error_code is the detailed code from the error table, and exit_code is the exit code number. message is in English when the CLI knows the code; otherwise it is the server's message as is (it may be in Vietnamese). When error_code is validation_error, the JSON also has errors: each rejected field and the reason. When the server sent a request ID, the JSON also has request_id; quote it to SePay when you report an HTTP 5xx.
For example, creating a webhook that turns off the main account number (off) on an account with no VA:
$ 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"}}Without --json the error prints as Error: the request failed validation, followed by one - bank_config: ... line per rejected field.
The login and auth commands can report OAuth error "unknown_error": the OAuth host returned an error without a code. unknown_error appears only in message; error_code is then error.
Handling errors automatically in scripts: Scripts.