Cloud Server Response & Error Catalog
The Cloud Server Error Catalog (Section 11.2) provides a standardized reference for interpreting the top-level status of any API response. These errors originate from the Getnet Cloud layer and indicate issues with request validation, terminal connectivity, or system timeouts.
Universal Response Wrapper
Every request sent to the API returns a consistent JSON wrapper to simplify state management and error parsing.
code: The primary status indicator:- 0: Error (The transaction encountered a problem on the server side).
- 1: Success / Accepted (The transaction is correct).
- 2: In Process (The transaction is active; final response is pending).
status: A string label matching the code. Typically "ERROR" for code 0 and "OK" for codes 1 and 2.message: A human-readable description of the result.data: The payload containing terminal-specific data. This is null if a server-side error occurs.
Server-Side Error Catalog (code: 0)
When the API returns
code: 0, refer to the table below for technical descriptions and required actions.| Error Message (English Equivalent) | Technical Description | Recommended Action |
|---|---|---|
| UNAUTHORIZED | Invalid or missing credentials. | Obtain a new token via the /auth endpoint. |
| ID NOT FOUND | The specific transaction ID does not exist. | Verify the idPosTxs and try again. |
| KEYPOS NOT FOUND... | The terminal identity triplet is incorrect. | Verify idTerminal, idSucursal, and serialNumber. |
| OPERATION IN PROGRESS (15s) | A command is currently running on the POS. | Wait 15 seconds before retrying. |
| OPERATION IN PROGRESS (5m) | A command is currently running on the POS. | Wait 5 minutes before retrying. |
| C2C SERVICE NOT RESPONDING | Cloud cannot reach the POS. | Confirm terminal power and internet stability. |
| TIMEOUT (90 SECONDS) | POS exceeded initial 90s window. | Wait; the system will continue waiting for 3.5m. |
| TIMEOUT (5 MINUTES) | POS exceeded maximum lifecycle window. | Query transaction status via the API. |
Success and Progress States
Status messages vary depending on the execution mode and transaction state.
Code 1: Success / Accepted
- Synchronous (
TRANSACTION FINALIZED): The operation is complete. Final data is available in thedatanode. - Asynchronous (
TRANSACTION SENT): The request reached the Cloud and was dispatched to the terminal. Wait for the webhook callback. - Authentication (
LOGIN SUCCESSFUL): Credentials validated; new Bearer token issued.
Code 2: In Process
- State (
TRANSACTION IN PROCESS): The terminal is currently interacting with the customer or the authorizer. - Data Node: The
datafield remains null until the POS returns a final result.
Operational Recovery Flow
If your software receives a
code: 0 due to a Timeout (specifically the 90-second or 5-minute errors), do not re-send the original request immediately.- Capture the ID: Locate the unique
idPosTxsfrom the initial response. - Verify State: Call the Status Query endpoint (
GET /api/postxs/{id}). - Finalize or Retry:
- If the query returns Code 1, finalize the sale in your local system.
- If the query returns Code 0 or Not Found, re-initiate the transactional request.
Next Steps
Now that you understand server responses, you can dive deeper into specific terminal outcomes and status tracking:
On this page
Cloud Server Response & Error Catalog