# Error Codes (/global/en/docs/Terminal/References/Error-Codes)

## Error Codes

When integrating with the SDK, you may encounter two distinct types of failures. Understanding the difference between them is essential for correct error handling.

### Two Types of Failures

| Scenario                            | Trigger                                   | How to Detect                    | Result Availability                      |
| ----------------------------------- | ----------------------------------------- | -------------------------------- | ---------------------------------------- |
| **1. Technical Execution Failure**  | Request fails before or during processing | onError callback is triggered    | No valid transaction result              |
| **2. Business Transaction Failure** | Request reaches host but is declined      | response = FAIL / PART in result | Transaction result returned with details |

### Scenario 1: Technical Execution Failure

The onError callback is triggered when a request fails due to technical reasons **before** a valid transaction result can be produced:

- Communication issues
- Configuration errors
- Validation failures
- Service unavailability

> **WARN**
>
> When onError is triggered, no transaction result is returned. The request did not reach the host or failed during transmission.

#### Error Code Table

1. Request & Routing Errors

| Code  | Description                                 |
| ----- | ------------------------------------------- |
| -1001 | Request rejected by the target system.      |
| -1002 | No matching response found for the request. |

2. Configuration Errors

| Code  | Description                                                                  |
| ----- | ---------------------------------------------------------------------------- |
| -1003 | Permission denied. Bluetooth permission required (e.g., BLUETOOTH\_CONNECT). |
| -1004 | LAN communication parameters not configured.                                 |
| -500  | Bluetooth MAC address connection failed or timed out.                        |

3. Communication & Service Errors

| Code | Description                             |
| ---- | --------------------------------------- |
| -99  | Unsupported LAN communication protocol. |
| -100 | Inter-process communication failed.     |
| -101 | Required service not available.         |

4. Network Errors

| Code | Description                          |
| ---- | ------------------------------------ |
| -200 | Failed to establish HTTP connection. |
| -201 | Invalid or failed HTTP response.     |
| -300 | RSocket I/O error occurred.          |

5. Validation Errors

| Code | Description                             |
| ---- | --------------------------------------- |
| -400 | Unsupported message format or mapper.   |
| -401 | Required fields are missing.            |
| -402 | Request message validation failed.      |
| -403 | Response validation failed.             |
| -404 | Missing required service-specific data. |

### Scenario 2: Business Transaction Failure

When a request is successfully transmitted and processed by the host, but the transaction itself is declined or partially approved, the SDK returns a **transaction result** (e.g., PaymentResult, RefundResult) with the response field set to FAIL or PART.

In this scenario:

- The onError callback is **not** triggered
- A valid transaction result object is returned
- Use the response and responseReason fields to determine the failure cause

#### Response Codes

The response field indicates the overall outcome of the transaction:

| Code | Meaning                        | Action Required                                       |
| ---- | ------------------------------ | ----------------------------------------------------- |
| SUCC | Success. Transaction approved. | Proceed with business logic.                          |
| FAIL | Failure. Transaction declined. | Check responseReason for details.                     |
| PART | Partially approved.            | Check responseReason; host approved a smaller amount. |

#### Response Reason Codes

When response is FAIL or PART, the responseReason field provides detailed failure information:

| Code | Meaning             | Typical Cause                                            |
| ---- | ------------------- | -------------------------------------------------------- |
| ABRT | Aborted             | The initiator sent an abort request.                     |
| BUSY | Busy                | System is temporarily overloaded; retry later.           |
| CANC | Cancelled           | User cancelled on the terminal (e.g., during PIN entry). |
| DEVO | Device Out of Order | Terminal hardware malfunction.                           |
| NHOS | Unreachable Host    | Acquirer or host did not respond; may retry.             |
| REFU | Refusal             | Host or local rules declined the transaction.            |
| TNFD | Not Found           | Original transaction not found (reversal/repeat).        |
| UNVD | Unavailable Device  | Required hardware not present or not configured.         |
| UNVS | Unavailable Service | Service not implemented or protocol too old.             |
| WIPG | In Progress         | Transaction is still processing; command rejected.       |
| WPIN | Wrong PIN           | PIN verification failed on the terminal.                 |

### Error Handling Decision Guide

| Check Point | Condition                  | What It Means     | Next Step                                              |
| ----------- | -------------------------- | ----------------- | ------------------------------------------------------ |
| Step 1      | Was onError triggered?     | Technical failure | Handle using onError codes above                       |
| Step 2      | Is result.response = FAIL? | Business decline  | Check responseReason for cause                         |
| Step 3      | Is result.response = PART? | Partial approval  | Host approved a smaller amount; check authorisedAmount |
| Step 4      | Is result.response = SUCC? | Full success      | Transaction completed normally                         |