Documentation

ZRA result codes

What each code means, where it reaches you, and whether to fix the data, wait, or stop the line.

ZRA result codes

Every fiscalised document gets a verdict from ZRA as a result code. 000 is success; everything else is a refusal or a deferral. This page is the vocabulary: which codes you will actually meet through the gateway, where they appear, and what to do about each one.

1. Where a result code reaches you

A 2xx from the gateway does not mean ZRA has accepted the document. The gateway is offline-tolerant: when ZRA is unreachable your sale is accepted, numbered and queued, and uploaded in invoice order once connectivity returns. Read the result the same way on every surface:

Surface Where to look
POST /api/v1/sales (and credit notes) data.status (uploaded / pending / failed) and data.resultCode on the 201; on a rejection, a 422 whose body carries top-level resultCode and resultMessage.
invoice.fiscalised / invoice.failed webhooks data.invoice.status, data.invoice.resultCode, data.invoice.lastError. This is how you learn the fate of a queued (pending) sale without polling.
POST /zm/api/Invoice A 422 whose body carries resultCode and resultMessage beside the legacy status / message / error fields. A queued sale returns 200 with signature and qrCode null.
GET /api/v1/sales/{id} The stored document, including its current status / resultCode — poll this only if you cannot receive webhooks.
GET /zm/api/Invoice/{ref} Fiscal details only — this response carries no status and no resultCode. A non-null signature means ZRA has the document; signature and qrCode both null means it is still queued. Poll on that, not on a status field.

Codes marked retryable below never surface as errors at all: the gateway queues the sale (status: pending) and retries. You meet them, at most, as the lastError on a document that is still waiting.

2. The codes

Code Meaning What you do
000 Accepted. The document is fiscal; print it. Nothing.
834 Invalid SalesType/ReceiptType combination. A gateway-construction bug rather than something you can send — report it to support with the invoice reference.
836 The device's sequences were altered; it must re-sync with ZRA before it can sign anything. Stop the line. Like 895, this is the device, not your document. Alert the merchant and contact support.
838 Retryable. The VSDC has no connection to the ZRA API. Nothing — the gateway queues the sale and retries. It stays pending; subscribe to invoice.fiscalised to learn when it lands.
884 Invalid customer TPIN. Fix customer.tpin (a TPIN is 10 digits) and resend. Send no TPIN at all for a walk-in customer.
894 Retryable. The ZRA API refused the connection. Nothing — queued and retried, as with 838.
895 Device configuration not found or corrupted; the device must be re-initialised. Stop the line. No document from this branch will succeed until an operator intervenes. Alert the merchant and contact support — never attempt re-initialisation yourself, it is one-shot per device and can burn it.
897 Retryable. VSDC database lock timeout. Nothing — queued and retried.
899 An unspecified VSDC client error. Before VSDC 1.0.11 this was the catch-all that also covered a keyless device; it is now only the residual case. Treat as "stop the line" until you know better, and escalate with the resultMessage.
901 The VSDC does not consider this a valid device. Stop the line, as with 895.
910 Request parameter rejected. Observed in production for date-rule violations (a salesDt outside ZRA's 180-day window or ahead of ZRA's clock); ZRA's table also uses it for a credit quantity exceeding the original. The 180-day floor and the credit-note amount are pre-validated in words, so a 910 for those is worth reporting. A date ahead of our clock is different: it is silently clamped to now rather than refused, so the document files under today's date. If a sale lands on the wrong day, check the till's clock — that is the cause, and it will not raise a 910.
913 Code value error among the request parameters — a field carries a value outside the code list ZRA accepts. Check the offending value against the relevant code list, fix and resend.
924 The CIS invoice number already exists. You should never see this: the gateway allocates invoice numbers per device. If you do, report it — do not renumber and resend yourself.
930 / 931 / 932 / 934 / 935 Credit-note validation: original invoice not found; amount exceeds the original; item not on the original; quantity exceeds the original; details do not match the original. Fix the credit note against the invoice it reverses and resend.

Where these come from. The meanings above are read from the VSDC's own ApiConst, because the VSDC is what answers your requests. Where the ZRA specification PDF numbers a code differently, the VSDC wins. Codes 801–805 in particular are the VSDC's internal resend/report bookkeeping, not sale verdicts, and you should not meet them on a sale.

Two codes are worth knowing about specifically, because ZRA's published response-code table (§6.13) has not caught up with the shipped VSDC:

  • 895 is "an error regarding unallowed Request Method" in ZRA's table, but "Device configuration not found or corrupted — re-initialize device" in VSDC 1.0.11.x. We document the VSDC's meaning because that is the software that answers you. If you are reading ZRA's PDF alongside this page, that is the one entry where the two genuinely disagree.
  • 897 does not appear in ZRA's table at all — it is new in the VSDC.

Anything else is a validation or comms error ZRA has not given a specific name. Treat an unlisted code as a data rejection: check your data first, then escalate with the resultMessage, which the gateway passes through verbatim.

3. The three rules worth automating

  1. Branch on resultCode, never on the message. resultMessage is ZRA's prose, passed through verbatim; the code is the contract.
  2. pending is not an error and not a success. Do not resubmit a pending sale — it is already queued in order and resubmitting can only create a second document. Mark the printed receipt provisional and finish it when invoice.fiscalised arrives.
  3. Distinguish "fix the data" from "stop the line". 884, 910, 913 mean this document is wrong — fix it and resend. 895, 901, 836 (and 899, now the residual case) mean the branch device is wrong — no document will succeed until an operator intervenes, so stop submitting and alert someone. Do not branch on 899 alone: VSDC 1.0.11 split it, and a broken device now answers 895 or 901.
Back to the guide API reference