This document provides a comprehensive reference for all error codes returned by the Connectivity Platform during vending transactions.
Vend Result Error Codes (Vend Callback)
These codes are returned via the /txn/vend callback when a vend (dispense) operation fails. The /txn/vend callback is called after the vending machine has attempted to physically dispense a product — these codes report the outcome of that physical dispense attempt.
| Code | Name | Meaning | Typical Cause |
|---|---|---|---|
| 1 | Cashless Peripheral State Invalid | The cashless device (card reader/telemetry module) was not in the correct MDB state to process the vend. | The cashless peripheral was busy, not yet initialized, or in an error state when the vend was attempted. Can happen if a second payment is initiated before the first completes. |
| 2 | New Payment Request Received | A new payment request interrupted the current one. | A second payment was initiated while the first was still in progress, causing the first to be cancelled. |
| 3 | Telemetry Device Reset | The telemetry device rebooted during the transaction. | Power interruption, firmware crash, watchdog reset on the telemetry module mid-transaction, or network disruption (e.g., 4G connectivity loss) causing the device connection to reset. |
| 4 | MDB Request Vend Cancel | The MDB bus explicitly sent a vend cancel command. | The vending machine’s VMC (Vending Machine Controller) cancelled the vend — could be due to a timeout, product jam detection, or operator intervention. |
| 5 | MDB Report Vend Failure | The vending machine reported the physical vend failed. | The VMC tried to dispense but the motor/mechanism failed — product jam, coil/motor failure, out-of-stock, or sensor didn’t detect the product drop. This is a mechanical failure reported via the MDB protocol. |
| 6 | Laundry Machine Code | Laundry-specific failure code. | Specific to laundry machine integrations. |
| 1000 | Unknown Code | Unrecognized code from device. | The device sent a code not in the known set. |
Unlock Request Codes (Unlock Callback)
These codes are returned via the /txn/unlock callback when a transaction session is terminated and the machine needs to be released.
The /txn/unlock and /txn/vend callbacks are mutually exclusive for a given transaction:
/txn/vendis called when the device explicitly reports a VENDED (success) or FAILURE (dispense failed) message./txn/unlockis called in all other termination scenarios: device session close, connection loss, timeout, or when the device reports the outcome via a session close message instead of a vend message.
Some unlock codes (e.g., 6 MDB Report Vend Success, 7 MDB Report Vend Failure, 12 Coil Failure) describe post-dispense outcomes. These occur when the device firmware reports the result through a session close rather than a dedicated vend/failure message.
| Code | Name | Meaning | Typical Cause |
|---|---|---|---|
| 0 | Legacy Code | Legacy unlock reason. | Older devices that do not report a specific unlock reason. |
| 1 | Device Connection Close | The connection between the telemetry device and the server was lost. | Network dropout (WiFi/cellular/4G), device went offline mid-transaction. |
| 2 | Vending Machine No Response After Payment Approval | Payment was approved but the vending machine didn’t respond. | The VMC didn’t acknowledge the vend command within the timeout period after the cashless session was approved. Could be a slow/unresponsive VMC or MDB bus communication issue. |
| 3 | Card Reader Declined | The card reader declined the payment. | Card was rejected by the reader hardware — could be a bad read, unsupported card, or reader malfunction. |
| 4 | Insufficient Credit | The customer does not have enough credit. | Account balance is too low for the selected product. |
| 5 | Charge Failed | The payment charge failed. | Payment gateway declined the charge — could be insufficient funds, expired card, or gateway error. |
| 6 | MDB Report Vend Success | The MDB bus reported the vend was successful. | This is not an error — it indicates the vend completed successfully and the lock can be released. |
| 7 | MDB Report Vend Failure | The MDB bus reported the vend failed. | The physical dispense mechanism failed (same as vend result code 5). |
| 8 | MDB Report Session Complete | The MDB session completed. | The cashless session ended normally. |
| 9 | Device Failed to Parse Code | The telemetry device could not parse the command. | Firmware bug or protocol mismatch between server and device. |
| 10 | Transaction Canceled by Payment Server | The payment server explicitly cancelled the transaction. | Server-side cancellation — could be due to timeout, duplicate detection, or administrative action. |
| 11 | Cardless Disabled | Cashless/cardless payment is disabled on the machine. | The machine’s VMC has cashless payment disabled in its configuration, so it rejected the cashless session. |
| 12 | Coil Failure | The dispense coil failed. | The motor/coil responsible for pushing the product failed to turn or jammed. |
| 999 | Card Reader Session Timeout | The card reader session timed out. | The card reader waited too long for a card tap/insert and the session expired. |
| 1000 | Unknown Code | Unrecognized code from device. | The device sent a code not in the known set. |
Lock API Errors
The /api/lock call is a blocking request that starts a transaction session on the vending machine. It locks the machine for the duration of the transaction so that no other payment session can begin concurrently.
Before calling /api/lock, it is recommended to first call /api/vmc_search to verify the machine is ready to accept payments. The /api/vmc_search response includes the following status fields:
| Field | Type | Description |
|---|---|---|
connected |
boolean | Whether the telemetry device has an active connection to the server. |
online |
boolean | Legacy field. true when the machine is connected and payment context is enabled. Equivalent to connected && ready. Kept for backward compatibility. |
ready |
boolean | Whether the machine’s payment context is enabled and the machine can accept cashless payments. |
busy |
boolean | Whether there is an ongoing transaction on the machine. |
Recommended pre-lock check: Verify that ready == true and busy == false before calling /api/lock.
If connected == true but ready == false, the machine is online but its cashless payment context is disabled (VMC issue). Calling /api/lock in this state will likely result in an unlock callback with code 11 (CARDLESS DISABLED).
Vending machine offline or not found
The platform cannot send the lock command because the machine’s telemetry device has no active connection to the server.
Typical Causes:
- Machine is powered off or in standby
- Cellular/WiFi connectivity lost
- Telemetry device rebooted and hasn’t reconnected yet
- Network firewall blocking outbound connections