Response and Error Codes

This reference describes the response and error codes used by Integrated POS operations. All operations return at least a numeric Code and a Message.

What are response and error codes

Every Integrated POS operation returns a response with a numeric Code (Int) and Message (String).

All values listed below are returned in the same Code field. The categorization into “Response Codes” and “Error Codes” is for documentation clarity and logical grouping only.

Response structure

All operations return a structured response containing at minimum:

Field	Type	Description
`Code`	String	Response code (see table below).
`Message`	String	Human-readable result.

A response code of 0 indicates success.

Common response codes

Code	Description
0	Operation executed successfully
1	Operation denied
2	Operation canceled by user
3	Error found during operation processing
4	Unknown error – check message details
5	POS Integrated still on WAITING_CONFIRMATION status. Send a Polling command to initiate.
6	Cancel operation executed successfully

Codes 2 and 6 both relate to cancellation but mean different things. 2 (Operation canceled by user) is returned by a command — Sale, Refund, or Pre-authorization — that was aborted. 6 (Cancel operation executed successfully) is returned by the Cancel command itself. Both apply to the SDK (USB / HTTP) and Cloud2Cloud modes.

Code 5 signals that the terminal must re-establish its connection (for example after a reboot or a dropped link). Re-run Polling on the same Connector, resend the setup parameters, then retry the command. See Polling and Reconnection.

When Code is 3 for Sale, Refund, Pre-authorization, or Shift, the Message field is a JSON-encoded string describing the failed validations. See Validation Errors.

Error codes for Integrated POS mode

These codes typically appear in activation, reconnection, or connection-loss scenarios.

The table below lists all error codes defined in the manual.

Code	Description
`1-500`	The terminal wasn’t able to initialize proper dependencies for open serial port.
`1-501`	Connectivity problem on trying to setup Wi-Fi connection. Check if Wi-Fi is enabled in terminal.
`1-502`	Error on try open the terminal serial port.
`1-503`	The user requested to exit Integrated POS Mode.
`A-503`	The Wi-Fi or USB connection is unexpectedly finished while the application is listening to commands.
`A-504`	The user is trying to quit Integrated POS Mode, but the application couldn’t close communication.
`A-505`	An interface disconnection was detected and the Integrated POS Mode was disconnected.
`G-XXXX`	Errors related to the Cloud Integration Provider, such as G-Services.
`S-100`	There was an internal error in POS or an interface disconnection and the communication was interrupted.

For connection-related codes (e.g. A-503, A-504, A-505, S-100), follow the reconnection flow described in the Core Concepts. Do not assume the Connector is still valid.

Transaction status codes

Returned in the Status field of a CheckStatus response. These describe the state of a past transaction, not the outcome of the CheckStatus command itself — that is in Code.

Status code	Status name	Description
0	`APPROVED`	Transaction captured. Used for standard card sales and QR Code with card.
1	`AUTHORIZED`	Transaction authorized (pre-authorization or QR PCT).
2	`REFUNDED`	Transaction refunded (D+1).
3	`CANCELED`	Transaction canceled (D+0).
4	`REVERSED`	Transaction reversed (undone).
5	`NOT_FOUND`	No transaction found for the given `CallerId`.
6	`UNKNOWN`	Unmapped status.

QR Code payment methods behave differently. QR PCT (Point of Capture) transactions always return AUTHORIZED and never APPROVED. QR Code with card follows the same behavior as a standard card sale.

Error handling guidelines

Always check the response Code before proceeding (e.g. 0 = success).
Do not retry operations blindly; revalidate terminal state with Polling after errors.
For code 5, send a Polling command before continuing.
For connection-related errors, follow the reconnection instructions in this documentation.

Reconnection, Polling, and Resilience — When to poll and how to recover.