Error Handling
Use the information in this section to diagnose API request failures, transaction processing issues, and terminal connectivity problems.
Terminal API errors generally fall into these categories:
HTTP & API errors
HTTP Errors occur when the API cannot process a request and returns an HTTP status code.
Common HTTP status codes
These status codes indicate whether the API successfully received and processed a request.
| HTTP Code | Meaning | Possible Cause |
|---|---|---|
| 200 OK | Request processed successfully | Request received and sent to the terminal |
| 301 Moved Permanently | Resource location changed | May occur in specific test environments |
| 400 Bad Request | Invalid request | Malformed JSON or invalid parameters |
| 401 Unauthorized | Authentication failed | Missing or invalid access token |
| 404 Not Found | Resource not found | Invalid endpoint, merchant ID, terminal ID, or disconnected terminal |
| 408 Request Timeout | Request timed out | Network latency or communication delay |
| 429 Too Many Requests | Rate limit exceeded | Internal processing failure |
| 500 Internal Server Error | Unexpected server error | Internal processing failure |
| 503 Service Unavailable | Service temporarily unavailable | Maintenance or platform disruption |
To improve reliability in production environments, implement retry logic with exponential backoff for transient errors such as 429, 500, and 503.
API errors
API errors occur when a transaction fails during processing. The API returns diagnostic information to help identify and troubleshoot the cause.
ResponseReason
A short, standardised reason code indicating why the transaction failed.
Examples:
- Refusal
- WrongPIN
- DeviceOut
- UserCancel
AdditionalResponseInformation
A detailed diagnostic message that helps you troubleshoot integration issues.
Format:
ERROR_CODE:DETAILED_MESSAGE
Example:
WPI_ERR_COND_MISSING_MANDATORY_PARAMETER
Terminal issues
Terminal issues occur when the terminal cannot connect to or communicate with the Terminal API service.
Quick checks
Verify the following before performing detailed troubleshooting:
- The Terminal API application is visible in the launcher.
- The device has internet connectivity.
- The UMID and UTID values are correct.
- The credentials are valid.
- The correct environment (Production or Integration) is selected.
- Outbound HTTPS connectivity (port 443) is available.
App not visible
Possible cause
- The application is not installed.
- Store synchronisation failed.
Resolution
- Open SmartPOS Store.
- Select the All tab.
- Verify that the Terminal API application is available.
- Retry the installation if necessary.
- Verify internet connectivity.
- Restart the device.
Invalid credentials
Possible cause
Incorrect UMID, UTID, or credentials.
Resolution
- Re-enter the UMID and UTID values exactly as issued.
- Verify that the selected environment is correct.
- Regenerate or retrieve new credentials if available.
Environment mismatch
Possible cause
Integration and Production environments are being mixed.
Resolution
- Verify the environment configured in the Terminal API application.
- Ensure that the terminal, credentials, and API endpoints use the same environment.
Activation issues
Possible cause
- Activation did not complete successfully.
- Network connectivity issues prevented activation.
Resolution
- Verify internet connectivity.
- Retry activation.
- Verify that the Terminal API application is up to date.
- Verify that the device date and time are synchronised.
Connectivity issues
Possible cause
Network policies prevent outbound communication.
Resolution
- Allow outbound HTTPS traffic on port 443.
- Verify DNS resolution.
- Check proxy and firewall settings.
- Test using an unrestricted network.
Display issues
Possible cause
Incomplete initialisation or a temporary user interface issue.
Resolution
- Restart the device.
- Retry the MENU sequence after startup completes.
Troubleshooting
Security
When troubleshooting:
- Do not expose sensitive identifiers in logs or screenshots.
- Review TLS certificate configuration and validation.
- Verify secure token handling and credential storage practices.
- Follow your organisation's security policies.
For advanced troubleshooting:
- Enable verbose logging, if available.
- Collect logs during provisioning and payment flows.
- Capture request and response details for traceability.
- Record transaction identifiers when investigating failures.
Validation
After configuration or troubleshooting is complete:
- Verify that the terminal appears in the cloud portal.
- Run a test provisioning operation, if applicable.
- Perform a sample payment transaction.
- Verify successful communication between the terminal and the Terminal API.
- Confirm that the expected transaction results are returned.
Troubleshooting for common error messages
"Invalid API Key":
Double-check the API key for any typos. Ensure that the key has not expired or been revoked.
"Service Unavailable":
Verify your network connection and check the API status page for any reported outages or maintenance.
"Transaction Failed":
Ensure all required fields are correctly filled in the request payload. Review any error codes in the response for specific issues.
"I receive an enexpected error for one particular transaction":
When working in test systems, when sending a round number as a total amount, it may trigger special errors. When working in test systems is better to use numbers with decimals.
"UnavailableDevice - WPI_ERR_COND_NOT_INITIALIZED:Terminal not configured" :
The terminal may not be initialized or configured correctly, and the following transactions may fail while the application is busy. Perform the initialization and configuration steps as described on the setup page before attempting to retry.