> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.qfapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction Status Codes

> Standard QFPay API response codes and recommended integration handling.

# Transaction Status Codes

The table below lists common `respcd` values returned by QFPay APIs.

<Note>
  `respcd = 0000` indicates the API request was processed successfully.

  The actual transaction result should be determined using business fields such as `txstatus` or by calling the Transaction Enquiry API.
</Note>

***

# Successful Response

| Code | Description            |
| ---- | ---------------------- |
| 0000 | Transaction successful |

***

# Request & Signature Errors

| Code | Description                       |
| ---- | --------------------------------- |
| 1102 | Duplicate request                 |
| 1103 | Request format error              |
| 1104 | Request parameter error           |
| 1108 | Signature error                   |
| 2011 | Transaction serial number repeats |

**Integration Guidance**

* Validate required parameters
* Ensure correct signature algorithm and sorting
* Ensure `out_trade_no` is unique per merchant

***

# Device & Store Status Errors

| Code | Description                                     |
| ---- | ----------------------------------------------- |
| 1105 | Device not activated                            |
| 1106 | Invalid device                                  |
| 1107 | Device not allowed                              |
| 1241 | Store does not exist or status incorrect        |
| 1242 | Store configuration error                       |
| 1243 | Store disabled                                  |
| 1251 | Store configuration issue (under investigation) |

**Integration Guidance**

* Verify merchant onboarding configuration
* Confirm device/store activation status
* Contact technical support if persistent

***

# Order State Conflicts

| Code | Description                  |
| ---- | ---------------------------- |
| 1125 | Transaction already refunded |
| 1142 | Order already closed         |
| 1181 | Order expired                |
| 1260 | Order already paid           |
| 1261 | Order not paid               |
| 1262 | Order already refunded       |
| 1263 | Order already cancelled      |
| 1264 | Order already closed         |
| 1266 | Transaction amount mismatch  |
| 1267 | Order information mismatch   |
| 1268 | Order does not exist         |

**Integration Guidance**

* Always query transaction status before retrying
* Avoid resubmitting payment requests blindly
* Ensure idempotent handling in your system

***

# Processing / Pending States

| Code | Description                                                      |
| ---- | ---------------------------------------------------------------- |
| 1143 | Order not paid yet or customer entering password                 |
| 1145 | Transaction processing                                           |
| 1298 | Network delay — if payment may have been completed, do not retry |

**Integration Guidance**

* Do not immediately retry
* Implement delayed polling via Transaction Enquiry API
* Prevent duplicate payment submission

***

# Payment Channel Errors

| Code | Description                             |
| ---- | --------------------------------------- |
| 1147 | WeChat Pay transaction error            |
| 1201 | Insufficient balance                    |
| 1202 | Invalid or expired payment code         |
| 1203 | Merchant account error                  |
| 1204 | Bank error                              |
| 1205 | Transaction failed                      |
| 1212 | UnionPay overseas payment code required |
| 1297 | Banking system busy                     |
| 2005 | Customer payment code expired           |

**Integration Guidance**

* Allow customer to retry payment
* Suggest alternative payment method if applicable

***

# Refund Restrictions

| Code | Description                                      |
| ---- | ------------------------------------------------ |
| 1150 | T0 settlement does not support cancellation      |
| 1155 | Refund request denied                            |
| 1265 | Refund not allowed during restricted time window |
| 1269 | Insufficient unsettled balance                   |
| 1270 | Currency does not support partial refund         |
| 1271 | Transaction does not support partial refund      |
| 1272 | Refund amount exceeds refundable limit           |

**Integration Guidance**

* Verify original transaction status before refund
* Check refundable balance
* Confirm payment channel refund rules

***

# System / Risk / Network Errors

| Code | Description                                   |
| ---- | --------------------------------------------- |
| 1100 | System under maintenance                      |
| 1101 | Reversal error                                |
| 1136 | Transaction not found or not operable         |
| 1250 | Transaction forbidden                         |
| 1252 | System error during request                   |
| 1254 | System exception                              |
| 1294 | Transaction prohibited by bank (risk control) |
| 1295 | Network congestion                            |
| 1296 | Network congestion, retry later               |

**Integration Guidance**

* Retry only when appropriate (e.g. 1295, 1296)
* Do not automatically retry risk-related errors (e.g. 1294)
* Log full request and response for troubleshooting

***

# Recommended Handling Strategy

1. Implement idempotency using `out_trade_no`
2. Query transaction status before retrying
3. Apply retry logic only for safe retry codes
4. Log all error responses for audit and reconciliation