SePay CLI exit codes and error codes

Look up SePay CLI exit codes and error_code values to see why a command failed, how to fix it and whether to run it again.

||

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

ExitMeaningAction
1General error: server error, network error, data rejected, quota exceededSee error_code.
2A 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 ruleCheck --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.
3The command isn't supported yetDon't retry. It runs only once a new CLI release supports it.
4Not signed in, or the token has expiredsepay login.
5The token lacks a scope on productionSign in again and grant the scope together with the ones you already have (Authentication).
6The handler didn't respond, or answered with a non-2xx status (or one other than --expect-status); only webhook test returns itCheck your handler and run again.
8The company or account doesn't have the feature enabledTest 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.
130The 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_codeExitMeaningActionRetryable?
validation_error1The submitted data was rejectedFix the fields listed in errors in the JSON.No
quota_exceeded1Quota exceeded (for example 500 transactions/day)Wait for the reset (00:00 Vietnam time) or raise the quota.No
rate_limited1Too many requestsThe CLI already waited per Retry-After and retried before failing. Wait longer, retry, and call less often.Yes
idempotency_conflict1An earlier command with the same --idempotency-key has not finished: it is still running, or it stopped midwayCheck 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_reuse1The --idempotency-key was already used for a different request (other flags or body)Use a new key.No
error1General error; the server sent no more specific codeRead message. With bankhub link-token get and pg order get it can mean the record wasn't found: don't retry.Depends
network_error1No usable answer came back from SePay: no connection, DNS failure, refused or cut connection, timeout, untrusted certificateCheck the network connection and run it again; for a command that creates data, keep the same --idempotency-key.Yes
server_error1SePay 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_failed1The sandbox isn't ready yetRetry.Yes
product_token_failed1SePay couldn't issue the product credential (pg, einvoice, bankhub)Retry, then report it to SePay.Yes
live_company_unresolved1SePay couldn't resolve your company for the requestsepay login.No
sms_not_allowed1Your plan doesn't include SMS connectionsUse --connection api.No
connection_not_supported1The bank has no API connectionPick another bank, or use --connection sms if your plan includes SMS.No
not_found1The endpoint exists only on sandbox; it isn't a missing record. The server's message, printed as is, says what to doRun it on sandbox.No
4041Bank Hub couldn't find the record; message is not found, or not visible to this merchantCheck the xid and --env: sandbox and production hold separate data.No
EINVOICE_DOCUMENT_NOT_FOUND1No invoice has this reference_codeCheck the code and --env.No
EINVOICE_ACCOUNT_NOT_FOUND1The company has no e-invoice provider accountSee eInvoice.No
4000, 4001, 40021pg order void was refused: the order is unpaid, already cancelled, or has no transactionCheck the order with pg order get (Payment Gateway).No
replay_not_dispatched1webhook 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_delivered1Production webhook replay: your handler already acknowledged the last delivery to this webhookCheck the order first. If you still need to re-send it, add --force and type the transaction id back when asked.No
replay_rate_limited1Production webhook replay: the transaction reached its replay cap, counted across all its webhooks. The CLI doesn't retry itWait until the time the message gives, then run again.Depends
replay_busy1Another replay of the same transaction is still runningWait a few seconds, then run again.Yes
paycode_prefix_exists1paycode 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_conflict1The payment code configuration changed after the command read it; nothing was savedRun the command again; if you passed --idempotency-key, use a new key.Yes
multiple_companies1The account belongs to several companiesUse an account that belongs to a single company.No
unsupported_api_version1The CLI is too oldUpdate the CLI.No
vcb_cancel_not_allowed1The order or VA can't be cancelled in its current state (sepay api only)Read the order's current state before cancelling.No
usage_error2A 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 ruleCheck --help. Sandbox: add --yes if it's a confirmation. Production: the user runs the command in their own terminal.No
not_implemented3The command isn't supported yetDon't retry.No
forward_failed6The handler didn't accept the notification sent by webhook testFix 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, unauthorized4Not signed in, or the token is invalidsepay login.No
access_revoked4Your sign-in session was revoked, so webhook listen stoppedsepay login, then run the command again.No
insufficient_scope5The token lacks a scopeSign in again and grant the scope together with the ones you already have.No
test_mode_disabled8Test mode isn't enabled for the companyA 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_provisioned8The company has no sandbox environment yetAsk SePay to provision it.No
sse_hub_disabled8Streaming is turned off on SePay's side; seen on the listen commands and webhook testContact SePay.No
forbidden, insufficient_role8Insufficient role or permissionAsk your company admin to grant the permission.No
blocked8An HTTP 403 without a more specific codeAsk SePay or your company admin.No
interrupted130You pressed Ctrl+C or Esc, or the command got SIGINT or SIGTERMRun 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:

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 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.