> ## Documentation Index
> Fetch the complete documentation index at: https://docs-payment-merchant.keysecure.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

<Note>
  * HTTP status code is generally **200**. Judge business success/failure through response body `code`; `code = 0` means success, non-zero means failure.
  * **Multi-language**: Request header `Language` controls Chinese/English (e.g., `zh_CN` / `en_US`).
  * Parameter error codes **1004, 2007–2010, 4010**, etc. include **snake\_case field name** before/after description.
</Note>

## Error Code Ranges

| code | Description                           |
| ---- | ------------------------------------- |
| 0    | Success                               |
| 1xxx | Common, auth, and PCI errors          |
| 2xxx | Cardholder errors                     |
| 3xxx | Account and transfer errors           |
| 4xxx | Card, transaction, and privacy errors |

## 9.1 Common / Auth / PCI (1xxx)

| code | Description                                               |
| ---- | --------------------------------------------------------- |
| 1001 | System error, please try again later                      |
| 1002 | Api-Key is required                                       |
| 1003 | IP address not allowed                                    |
| 1004 | Invalid request parameter                                 |
| 1005 | Timestamp invalid or expired                              |
| 1006 | Access-Token is required                                  |
| 1007 | Access-Token invalid or expired                           |
| 1008 | Api-Key does not exist                                    |
| 1009 | Operation too frequent, please try again later            |
| 1010 | Api-Key is not enabled                                    |
| 1011 | Api-Key has expired                                       |
| 1012 | Merchant integration mode not supported                   |
| 1013 | PCI sensitive card display is not enabled                 |
| 1014 | Client-Access-Token invalid or already used               |
| 1015 | Parent page Origin not in whitelist                       |
| 1016 | Request Origin does not match hosted configuration        |
| 1017 | Request replay or nonce already used                      |
| 1018 | Sec-Fetch validation failed                               |
| 1019 | Query end time must be after start time                   |
| 1020 | Query time range exceeds the allowed limit                |
| 1021 | Merchant does not exist                                   |
| 1022 | Merchant status is abnormal, please contact administrator |

## 9.2 Cardholder (2xxx)

| code | Description                                                                          |
| ---- | ------------------------------------------------------------------------------------ |
| 2001 | Cardholder already exists                                                            |
| 2002 | Cardholder does not exist                                                            |
| 2003 | Cardholder already verified                                                          |
| 2004 | Cardholder has a pending verification                                                |
| 2005 | Cardholder verification failed                                                       |
| 2006 | Failed to retrieve cardholder KYC information                                        |
| 2007 | Please use English letters, numbers, spaces, or common address symbols (e.g. - / #). |
| 2008 | Only English is supported                                                            |
| 2009 | Country is not supported                                                             |
| 2010 | The postal code does not match the selected address (state/province, city)           |
| 2011 | Cardholder unique number mismatch                                                    |

## 9.3 Account / Transfer (3xxx)

| code | Description                                 |
| ---- | ------------------------------------------- |
| 3001 | Currency not supported by merchant          |
| 3002 | Insufficient cardholder account balance     |
| 3003 | Currency chain mismatch                     |
| 3004 | Transfer reference number already exists    |
| 3005 | Invalid transfer amount format or precision |
| 3006 | Invalid transfer type                       |
| 3007 | Insufficient merchant account balance       |
| 3008 | Insufficient account balance                |

## 9.4 Card / Consumption / PIN / Privacy (4xxx)

| code | Description                                                                                                       |
| ---- | ----------------------------------------------------------------------------------------------------------------- |
| 4001 | Card BIN not available                                                                                            |
| 4002 | Card package not found                                                                                            |
| 4003 | Merchant card unique number already exists                                                                        |
| 4004 | Card does not exist                                                                                               |
| 4005 | Card status does not allow this operation                                                                         |
| 4006 | Card issuance limit reached                                                                                       |
| 4007 | Card provider operation failed                                                                                    |
| 4008 | Physical card activation must be completed in merchant app                                                        |
| 4009 | Card transaction record not found                                                                                 |
| 4010 | Physical card billing address cannot be empty                                                                     |
| 4011 | Country not supported for this card application                                                                   |
| 4012 | Card information not found                                                                                        |
| 4013 | Card status not supported                                                                                         |
| 4014 | Card activation not supported                                                                                     |
| 4015 | PIN decryption failed, check encryption method and key                                                            |
| 4016 | Invalid PIN format. Must be 6 digits without three identical or consecutive digits (e.g. 111111, 123456, 654321). |
| 4017 | Not a physical card, PIN setting not supported                                                                    |
| 4018 | No available API credential found                                                                                 |
| 4019 | CVV decryption failed, check encryption method and key                                                            |