ZRA VSDC Error 899: "An Error Regarding the Client Occurred"

899 shows up on calls that have nothing obviously in common:

• branches/selectBranches
• notices/selectNotices
• itemClass/selectItemsClass
• code/selectCodes

All returning the same thing:

{ "resultCd": "899", "resultMsg": "An error regarding the Client occurred." }

The message is not much help — "the client" is you, and it does not say what about you is wrong.

In our experience, 899 on these read calls means one thing: your VSDC has no device key. The call fails before it does anything, because the device it is calling on behalf of was never successfully authenticated.

Why it happens

Trace it back. These calls are authenticated with the cmcKey — the device key ZRA issues during initialisation. No key, no authenticated call.

So the question is not "why is selectBranches failing". It is "why do I not have a key". And the answer is almost always:

Initialisation returned 902 "This device is installed", so no key was ever issued.

ZRA issues the cmcKey exactly once, at the first successful initialisation of a serial. If your serial had already been initialised somewhere else — an earlier setup, another VSDC, a vendor's test — then your init returns 902, you get no key, and every authenticated call afterwards returns 899.

The chain:

Serial already initialised elsewhere
        ↓
Init returns 902 "This device is installed" — no cmcKey issued
        ↓
No device key stored on your side
        ↓
Every authenticated call → 899 "An error regarding the Client occurred"

The 899 is the symptom. The 902 is the disease.

Confirming it takes two checks

1. Do you hold a device key? In Account Desk the branch card shows a "key ✓" badge once one has been captured. In your own integration, look for cmcKey in whatever you stored from the init response. If it is empty, that is your answer.
2. What did initialisation actually return? Look at the raw response to initializer/selectInitInfo. If it is 902, you have found it.

If both point the same way, stop debugging the read call. There is nothing wrong with it.

The fix

Get a key. Which means initialising a serial that has never been initialised before:

1. Register a new device with a fresh serial — one that has never been used. It is a logical identifier you assign, not hardware.
2. Initialise it.
3. ZRA issues a cmcKey. Store it encrypted — it is a credential, not a config value.
4. The 899s stop. All of them, at once.

The full reasoning is in ZRA Smart Invoice error 902.

When it is not the key

899 is a generic client-side error, so the missing key is not the only possible cause. If you have confirmed you hold a key and calls still return 899:

• Check the key is actually being sent on the call, and that you are sending the device's own key rather than a manually entered API key left over from setup.
• Check the device is still valid in the environment you are calling. A device initialised against sandbox has no standing against production — that usually shows up as 901, but a mismatched setup can surface either way.

Start with the key, though. That is the cause we have hit every time.

Do not confuse 899 with 896

These two look similar and mean opposite things.

• 899 — "An error regarding the Client occurred." Your side. Usually no device key.
• 896 — "An error regarding request status occurred", often with : 404 in the message. That is your VSDC reporting that ZRA's endpoint answered 404. Your VSDC is up, your payload reached it, and the upstream service did not serve the request.

That distinction is not academic. We have seen 896 with : 404 on items/saveItem and stock/saveStockItems against production while trnsSales/saveSales returned 000 on the same device, same VSDC, in the same minute. Sales were fiscalising perfectly; only the inventory endpoints 404'd. Sending the same payloads to the sandbox host returned 000 for all of them — identical code, identical build, the only variable being which ZRA host was on the other end.

When that happens, no amount of payload debugging will help, because the payload is fine. It is a question to put to ZRA about what is enabled on your production account — not something to fix in your code.

The rule of thumb:

| Pattern | Meaning | |---|---| | All authenticated calls fail | It is your key | | Some endpoints fail, others succeed on the same device | It is not your payload — look upstream |

Related

• ZRA Smart Invoice error 902: "This device is installed" — the cause of most 899s
• ZRA Smart Invoice error 901: "It is not a valid device" — when initialisation is rejected outright

---

If you are setting up ZRA Smart Invoice and would rather not spend a week on device errors, Account Desk connects to Smart Invoice (VSDC) directly — a sale is fiscalised as you bill it, and the ZRA receipt number, SDC ID and QR code print on the invoice. Talk to our team about your Smart Invoice setup, or book a demo.