Error Handling for the eInvoice API

This page collects everything about eInvoice API errors in one place: the error response shape, the meaning of each error code, the automatic retry mechanism, and how to proceed when an invoice is not issued.

Two kinds of error

Error response shape

Every endpoint returns errors in the same shape:

{
  "success": false,
  "error": {
    "code": "EINVOICE_DOCUMENT_EXISTED",
    "message": "Hệ thống đã ghi nhận hoá đơn cho mã tham chiếu này."
  }
}

Handle errors based on error.code, not by matching the error.message string. message is Vietnamese text intended for display or logging, and its wording may change.

Error classification

HTTP errors

Common error codes

QUOTA_HAS_BEEN_USERD_UP is spelled exactly as the API returns it, typo included.

Each endpoint also has its own Error Handling table listing every code it can return, for example Issue Invoice and Issue from Draft.

Retry schedule

The create and issue APIs are asynchronous: the response returns a tracking_code and the remaining processing runs in the background. When that background work hits a transient error, SePay retries automatically, with the gap between attempts growing on a Fibonacci curve:

That is 8 attempts in total (the first one plus 7 retries), spanning roughly 33 minutes if every attempt fails.

Besides the attempt count there is a second limit: a request created more than 2 hours ago is no longer retried, even if attempts remain. It is a safety net for an attempt that hangs. This limit is normally never reached, because the 33-minute schedule finishes first.

Only infrastructure errors are retried: the invoice provider returns 5xx, a timeout, a connection loss, or an attempt interrupted midway. An error caused by the data or the account state returns the same result on every attempt, so the system returns Failed immediately.

The retry block in the status response

When status is Pending and the request has hit a transient error at least once, both status APIs return an extra retry block:

{
  "status": "Pending",
  "retry": {
    "retries_count": 2,
    "max_retries": 7,
    "next_retry_at": "2026-09-04 15:12:30"
  }
}

Two points are easy to misread:

• No retry block: the request has not failed yet and is waiting for its first attempt, not that retries are disabled.
• next_retry_at set to null: no further retry is scheduled, because all 7 retries are spent or the 2-hour window has passed, and the final result is being settled. It does not mean a retry is imminent.

Diagnosing an invoice that is not issued

Check the following in order. The cause is usually in the first few steps.

1. Check the response

success: false is a synchronous error, read error.code against the tables above. success: true with a data.tracking_code means the request was accepted, continue to step 2.

2. Check the environment

Production is https://einvoice-api.sepay.vn, Sandbox is https://einvoice-api-sandbox.sepay.vn. A token only works on the environment that issued it, and a Sandbox token sent to Production returns 401. See Sandbox.

3. Check the token validity

A token is valid for 24 hours. A long-running process reusing a token cached from the previous day receives 401 TOKEN_EXPIRED partway through. Fetch a new token on 401, rather than on every request.

4. Check status

Call Creation Status or Issuance Status with the tracking_code.

5. The invoice is still a draft

Sending is_draft: true on create leaves the invoice as a draft: it is not sent to the tax authority and does not count against the quota. Issue from Draft must be called to issue it.

6. Check the quota

Once the quota is exhausted, every issuance request returns Failed for the same reason. Call the Usage Quota API to see the remaining balance.

7. Check the tax authority approval

While the registration is unapproved, no invoice can be issued. Check tax_authority_approved_date in List Providers. The invoice date must also be on or after that date.

Before you resend

Failed does not mean that no invoice was created. Check before resending:

1. Call Invoice Details with your reference_code.
2. A 404: no invoice was recorded, resending is safe.
3. Invoice data: the invoice already exists, do not resend. Read its status to see whether it still needs to be issued or is already complete.

The Issue Invoice API guards against this case: resending the same reference_code after an invoice has been recorded for it returns 409 EINVOICE_DOCUMENT_EXISTED. This guard is not a substitute for the check above. Generate one unique reference_code per invoice, and reuse exactly that code when resending.

Frequently asked questions

Next

• Creation Status: the full status API response
• Issuance Status: the full status API response
• Invoice Details: look up an invoice by reference_code
• Usage Quota: remaining issuance balance
• Sandbox: test environment to use before going live