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

# HaiPay 错误码与错误返回说明

> 错误信息参考

## 响应结构

| 字段 | 类型 | 说明 |
| :- | :- | :- |
| status | String | 调用结果：`1` 成功，`0` 失败 |
| error | String | 请求成功为 `00000000`，失败为对应错误码（见下表） |
| msg | String | 结果描述：成功为空字符串，失败为错误说明文本 |
| data | Object | 业务数据：失败时为 `null` |

<Warning>
  `error` 字段不是固定契约：

  * **含义因响应来源而异**：
    * API 接口响应失败时 `status="0"`、`error` 为对应错误码（见本页各场景章节）；
    * 商户后台与收银台页面响应失败时仅 `status="0"`、`error` 保持 `00000000`（与成功值相同），提示文案在 `msg` 中；
    * 订单失败时查询接口仍返回 `status="1"`、`error="00000000"`，实际结果在 `data.status` 与 `data.errorMsg` 中
  * **随时可能变动**：错误码与错误文案可能随版本迭代新增、调整或改变含义，请勿将 `error` 码值或 `msg` 文案直接用于业务结果判断。
</Warning>

**成功响应**

```json theme={null}
{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {}
}
```

**失败响应（以缺少必填参数为例）**

```json theme={null}
{
  "status": "0",
  "error": "1002",
  "msg": "The field 'name' is required",
  "data": null
}
```

## 错误信息总览

| 错误信息编码 | 场景大类 | 描述 |
| :- | :- | :- |
| `1001` | 必填参数为空 | 缺少必填字段或字段为空 |
| `1002` | 参数非法 / 业务校验未通过 | 最常见，参数格式、金额、账户、订单等校验失败 |
| `1003` | 系统异常 | 服务内部异常。**订单可能已入库，请等待异步通知或查询订单确定最终状态**，勿直接判定失败。 |
| `1004` | 系统繁忙 | 系统繁忙或处理超时。**订单可能已入库，请等待异步通知或查询订单确定最终状态**；可稍后重试。 |
| `2001` | 汇率未配置 | 请求币种汇率未配置 |
| `2002` | 未开通汇率查询 | 当前商户未开通汇率查询能力 |
| `4031` | 访问 IP 未授权 / 地区受限 | 请求 IP 不在白名单，或所在地区被限制访问 |
| `4038` | 商户能力受限 | 代收/代付能力未开通或入驻状态受限 |
| `70000102` | 请求格式不正确 | Content-Type 或请求报文不可解析 |
| `70000103` | 缺少令牌 / JSON 格式错误 | 缺少 token，或请求体 JSON 格式错误 |

## 按场景的错误明细

### 签名、鉴权与访问权限

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `Invalid request signature` | 验签失败。检查签名算法、参与签名的字段与排序、编码格式，以及公私钥是否匹配。 |
| `70000103` | `Miss token.` | 缺少访问令牌。按接口说明携带正确令牌后重试。 |
| `70000102` | `Request format incorrect.` | 请求格式错误。确认 `Content-Type: application/json` 且报文可解析。 |
| `70000103` | `json format incorrect.` | 请求体 JSON 格式错误。校验 JSON 合法性后重试。 |
| `4031` | `client ip is in a region where access is forbidden` | 请求 IP 所在地区被限制访问。确认发起请求的服务器地区与网络环境。 |
| `4031` | `<your-ip> not in ip white list` | 请求 IP 未在白名单内。在商户后台配置服务器出口 IP 白名单后重试。 |
| `1002` | `ip error` | 请求 IP 校验未通过，请联系支持核对配置 |

**验签失败示例**

```json theme={null}
{
  "status": "0",
  "error": "1002",
  "msg": "Invalid request signature",
  "data": null
}
```

### 商户能力与入驻状态

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `4038` | `Your acquiring capability is restricted. Please check your onboarding status or contact customer support.` | 代收能力受限。检查入驻/开通状态，或联系 HaiPay 支持。 |
| `4038` | `Your disbursement capability is restricted. Please check your onboarding status or contact customer support.` | 代付能力受限。检查入驻/开通状态，或联系 HaiPay 支持。 |

### 必填参数缺失

补齐对应必填字段后重试。字段名以具体接口为准。

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `The field 'name' is required` | 姓名为空 |
| `1002` | `The field 'email' is required` | 邮箱为空 |
| `1002` | `The field 'accountNo' is required` | 收款账号为空 |
| `1002` | `The field 'phone' is required` | 手机号为空 |
| `1002` | `The field 'bankCode' is required` | 银行代码为空 |
| `1002` | `The field 'subject' is required` | 商品名称（交易标题）为空 |
| `1002` | `The field 'orderNos' is required` | 订单号列表为空（批量查询 / 凭证下载场景） |
| `1001` | `The field 'partnerUserId' is required` | 商户用户标识为空 |
| `1002` | `Email cannot be empty` / `Phone number cannot be empty` | 收款人邮箱 / 手机号为空 |
| `1001` | `Account number cannot be empty` | 收款账号为空 |
| `1002` | `Account information should not be empty.` | 收款账户信息不完整（账号或姓名缺失） |
| `1001` | `The field 'accountType' is required` | 缺少账户类型参数 |
| `1001` | `The field 'amount' is required` | 缺少金额参数 |
| `1001` | `The field 'appId' is required` | 缺少 appId 参数 |
| `1001` | `The field 'inBankCode' is required` | 缺少银行代码参数 |
| `1001` | `The field 'payType' is required` | 缺少支付方式参数 |
| `1001` | `The field 'sign' is required` | 缺少签名参数 |

### 参数格式非法

字段格式、长度或取值不符合要求。请对照对应接口页的字段规则修正。

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `Invalid format for field 'phone'` | 手机号格式不符 |
| `1002` | `Invalid format for field 'email'` | 邮箱格式不符 |
| `1002` | `Invalid format for field 'accountNo'` | 账号格式不符 |
| `1002` | `Invalid format for field 'payType'` | 支付方式取值不符 |
| `1002` | `Invalid format for field 'country'` | 国家/地区取值不符 |
| `1002` | `Invalid format for field 'CPF'` / `'ifsc'` / `'bankcode'` | 证件号 / IFSC / 银行代码格式不符 |
| `1001` | `Invalid format for field 'partnerUserId'` | 商户用户标识格式不符 |
| `1002` | `Amount format is invalid` | 金额格式不符 |
| `1002` | `IBAN format is invalid.` / `Swift code is invalid.` | IBAN / Swift 格式不符 |
| `1002` | `Invalid CLABE account number format or check digit` | CLABE 账号格式或校验位错误 |
| `1002` | `The name can only contain English letters and spaces` | 姓名仅允许英文字母与空格 |
| `1002` | `The name contains at least firstName and lastName, separated by spaces` | 姓名需含名与姓，以空格分隔 |
| `1002` | `The firstName and lastName can't be the same` | 名与姓不能相同 |
| `1002` | `birth is not a valid date` / `gender is not valid` | 出生日期 / 性别取值不符 |
| `1002` | `idCard must be 13 digits` | 证件号位数不符 |
| `1002` | `accountNo must be 11 digits starting with 0` | 账号位数/前缀不符 |
| `1002` | `recipient_account length must be 16 or 18 digits` | 收款账号长度须为 16 或 18 位 |
| `1002` | `Invalid format for field  'callBackUrl'` | 回调地址格式不合法 |
| `1002` | `Invalid format for field  'clientIp'` | 客户端 IP 格式不合法 |
| `1002` | `Invalid format for field  'notifyUrl'` | 异步通知地址格式不合法 |
| `1002` | `Invalid format for field 'amount'` | 金额格式不合法 |
| `1002` | `Invalid format for field 'callBackFailUrl'` | 失败回调地址格式不合法 |
| `1002` | `Invalid format for field 'cancelUrl'` | 取消地址格式不合法 |
| `1002` | `Invalid format for field 'customerIp'` | 客户 IP 格式不合法 |
| `1002` | `Invalid format for field 'orderNo'` | 订单号格式不合法 |
| `1002` | `Please configure the merchant public key` | 未配置商户公钥，请先在商户后台完成密钥配置 |
| `1002` | `orderId is too long` | 商户订单号超过 48 字符上限 |
| `1002` | `partnerUserId is too long` | 商户用户标识超过 64 字符上限 |
| `1002` | `partnerUserId must be either numbers, lowercase letters, uppercase letters, or common symbols` | 商户用户标识仅允许数字、大小写字母与常用符号 |
| `1002` | `phone is too long` | 手机号超过 20 字符上限 |

### 金额与限额

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `Amount is outside the allowed range` | 金额超出该市场/支付方式的限额范围。查阅对应国家接口页的限额后调整。 |
| `1002` | `Amount decimal places cannot exceed 2` | 金额小数位超过 2 位。按币种精度调整（部分币种不支持小数）。 |
| `1002` | `Amount does not support decimal places` | 该币种金额不支持小数位。 |
| `1002` | `Amount must be an integer` | 金额须为整数。 |

**金额超限示例**

```json theme={null}
{
  "status": "0",
  "error": "1002",
  "msg": "Amount is outside the allowed range",
  "data": null
}
```

### 收款账户信息（代付）

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `please put the right accountNo` | 收款账号不合法 |
| `1002` | `please put the right name` | 收款人姓名不合法 |
| `1002` | `The field 'accountType' only supports EWALLET` | 该场景账户类型仅支持 EWALLET |
| `1002` | `please put the more than 14 characters accountNo when accountType is BANK_CARD` | 银行卡类型账号长度不足 |
| `1002` | `BANK_CARD Number must be input when recipient_account is 16 digits` | 16 位收款账号须填写银行卡号 |
| `1002` | `BANK_ACCOUNT Clabe must be input when recipient_account is 18 digits` | 18 位收款账号须填写 CLABE |

### 订单相关

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `order not Exist or do not config callBackUrl` | 订单不存在，或未配置回调地址 |
| `1002` | `orderNos can not exceed 100` | 批量查询订单号数量超过 100 |
| `1002` | `please request the right url` | 请求地址不正确 |
| `1002` | `getfee is error, must 0, 1 or none` | 代付查询参数 `getfee` 取值须为 0、1 或不传 |
| `1002` | `isamount is error, must 0, 1 or none` | 代付查询参数 `isamount` 取值须为 0、1 或不传 |
| `1002` | `order already exist` | 商户订单号已存在，请勿重复下单 |
| `1002` | `order not exist` | 订单不存在 |

### 密钥与加解密配置

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `Public key is not configured.` | 未在商户后台配置公钥，请先完成密钥配置。 |
| `1002` | `Private key is not configured.` | 未配置私钥，请先完成密钥配置。 |
| `1002` | `The public and private keys do not match.` | 公私钥不匹配，请重新生成并上传匹配的密钥对。 |
| `1002` | `decryption failed.` / `encryption failed.` / `signing failed.` | 加解密或签名失败，请检查密钥与算法配置。 |

### 汇率查询

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `2001` | `exchange rate is not configured` | 请求币种汇率未配置，联系 HaiPay 支持 |
| `2002` | `current user has not enabled exchange rate query` | 未开通汇率查询能力 |
| `1004` | `rate error` | 汇率获取失败，可稍后重试 |
| `1001` | `The field 'currency' is required` | 缺少币种参数 |
| `1001` | `The field 'sourceCurrency' is required` | 缺少源币种参数 |
| `1001` | `The field 'targetCurrency' is required` | 缺少目标币种参数 |
| `1002` | `payType and inBankCode must be provided together` | payType 与 inBankCode 须同时传递 |
| `1002` | `please send right currency` | 请求币种与业务配置不符 |
| `1002` | `the app does not support this currency.` | 当前应用不支持该币种 |

### 支付方式与银行代码

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `Field 'bankcode' is invalid or the specified bank is not supported` | 银行代码无效或该银行不支持 |
| `1002` | `Invalid format for field 'bankcode'` | 银行代码格式不符 |
| `1002` | `please specify the MXN payment method (OXXO or PAYCASH)` | 墨西哥比索须指定支付方式（OXXO 或 PAYCASH） |

### 应用（appId）

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `Application ID not found` | appId 不存在，请核对后台获取的 appId |
| `1002` | `Application ID is disabled` | appId 已停用，请联系 HaiPay 支持 |

### 系统繁忙与处理超时

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1003` | `system exception` | 系统内部异常。请使用相同 `orderId` 指数退避重试，避免重复下单。 |
| `1004` | `system is busy` | 系统繁忙或处理超时。请稍后重试；涉及资金的操作请先查询订单最终状态。 |

### 凭证 / PDF 生成

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `PDF generation failed: PDF data is empty` | 凭证数据为空，稍后重试；持续失败请联系支持 |
| `1002` | `PDF generation failed: response data is null` | 凭证生成无返回数据，稍后重试 |
| `1001` | `The field 'orderNo' is required` | 缺少订单号参数 |
| `1002` | `PDF generation failed` | 凭证 PDF 生成失败，稍后重试 |
| `1002` | `The order was not successful` | 仅成功订单可获取凭证 |

### 订阅

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1001` | `The field 'country' is required` | 缺少国家/地区参数 |
| `1001` | `The field 'recurringInterval' is required` | 缺少循环周期类型（D/W/M/Y） |
| `1001` | `The field 'recurringIntervalCount' is required` | 缺少循环周期间隔 |
| `1001` | `The field 'recurringMaxNumber' is required` | 缺少最大循环次数 |
| `1001` | `The field 'subscriptionNo' is required` | 缺少订阅单号 |
| `1001` | `The field 'subscriptionOrderId' is required` | 缺少商户订阅订单号 |
| `1001` | `The field 'website' is required` | 缺少交易网站参数 |
| `1002` | `Coupon amount per period cannot be greater than order amount` | 每期优惠金额不能大于订单金额 |
| `1002` | `Invalid format for field  'recurringInterval'` | 循环周期类型取值不合法（仅 D/W/M/Y） |
| `1002` | `Invalid format for field 'couponAmountPerPeriod'` | 每期优惠金额格式不合法 |
| `1002` | `Invalid format for field 'couponPeriod'` | 优惠期数取值不合法 |
| `1002` | `Invalid format for field 'recurringIntervalCount'` | 循环周期间隔须为大于 0 的整数 |
| `1002` | `Invalid format for field 'recurringMaxNumber'` | 最大循环次数须为大于 0 的整数 |
| `1002` | `Invalid format for field 'retryTimes'` | 重试次数须为大于等于 0 的整数 |
| `1002` | `Invalid format for field subscriptionNo` | 订阅单号格式不合法 |
| `1002` | `The amount can have at most two decimal places` | 订阅金额最多两位小数 |
| `1002` | `The couponAmountPerPeriod can have at most two decimal places` | 每期优惠金额最多两位小数 |
| `1002` | `The final payment amount must be greater than or equal to the minimum subscription amount` | 最终支付金额须不低于最小订阅金额 |
| `1002` | `The subscription period cannot exceed three years` | 订阅周期不能超过三年 |
| `1002` | `coupon param error` | 优惠参数校验失败：优惠期数与优惠金额须同时传或同时不传 |
| `1002` | `couponPeriod must equal 1 or be equal to recurringMaxNumber` | 优惠期数仅支持首期或全期 |
| `1002` | `subscriptionOrderId is too long` | 订阅订单号超过 48 字符上限 |

### 退款

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `Refund order do not exist` | 退款单不存在 |
| `1002` | `Refund order refundType is wrong` | 该退款类型不支持查询 |
| `1002` | `The Refund order has been refunded` | 退款单已退款或退款处理中 |
| `1002` | `The Refund order refundFee is wrong` | 退款手续费取值不合法 |
| `1002` | `The order has exceeded 180 days` | 订单超过 180 天不可退款 |
| `1002` | `The order status is not success` | 仅成功订单可申请退款 |
| `1002` | `The refund application number cannot be duplicated with the original transaction number` | 退款申请单号不能与原交易单号相同 |
| `1002` | `account is null` | 商户余额账户信息不存在，请联系支持 |
| `1002` | `request param is wrong[orderId or refundNo Cannot all be empty]` | 商户退款单号与平台退款单号不能同时为空 |
| `1002` | `update account is fail` | 余额更新失败，请稍后查询订单状态 |

### 余额与扣款

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `Account balance is not enough` | 商户账户余额不足（代付下单、退款申请等场景） |
| `1002` | `Failed to update account balance.` | 余额扣减或扣款流水创建失败，请稍后查询订单状态 |
| `1002` | `The order amount is not enough to deduct the merchant fee` | 订单金额不足以扣除商户手续费 |

### 对账文件

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1001` | `The field 'date' is required` | 缺少对账日期参数 |
| `1001` | `The field 'type' is required` | 缺少对账文件类型参数（15 代付 / 20 代收 / 40 流水） |
| `1002` | `Unsupported file type` | 对账文件类型仅支持 15/20/40 |

### 全球收银台

| 错误信息编码 | 错误信息 | 描述 |
| :- | :- | :- |
| `1002` | `Cashier not configured` | 收银台业务未配置，请联系支持 |
| `1002` | `Invalid format for field orderNo` | 订单号格式不合法 |
| `1002` | `partnerUserId is blocked"` | 该用户标识已被限制下单，请联系支持 |
| `1002` | `please request the right currency` | 请求币种与业务配置不符 |
| `1002` | `Missing KYC configuration URL` | 入驻认证配置不完整，请联系支持 |

## 商户后台常见错误

本章错误提示出现在**登录与操作商户后台**的过程中（非 API 接口返回），请按描述处理；如持续出现，请携带错误提示与错误编码联系 HaiPay 支持。编码为后台服务错误码，与 API 错误码（1001/1002 等）属不同体系；`—` 表示该提示无独立识别码。

### 登录与会话

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `2023` | `user do not exist or password is incorrect.` | 用户名不存在或密码错误 |
| `2020` | `user has been deactivated, please contact customer service.` | 账号已被停用，请联系客服 |
| `2021` | `password error '<n>' times, account locked for '<m>' minutes, please contact customer service` | 密码错误次数过多，账号被临时锁定；请等待提示的分钟数后重试，或联系客服 |
| `—` | `verification failed. please refresh and try again.` | 页面安全校验失败，请刷新后重试 |
| `2005` | `login status has expired, need to log in again.` | 登录状态已失效，请重新登录 |
| `2028` | `we detected that your account was logged in on another device. for your security, this session has been terminated.` | 账号在另一设备登录，为保障安全本次会话已结束；如非本人操作请立即修改密码 |

### 安全验证（MFA 与验证码）

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `2014` | `please enter the email verification code` | 请输入邮箱验证码 |
| `2012` | `please enter the correct email verification code` | 邮箱验证码不正确，请核对后重新输入 |
| `2017` | `email authenticator not bind, please contact the customer service` | 邮箱认证器未绑定，请联系客服处理 |
| `2008` | `please enter the verification code` | 请输入身份验证器验证码 |
| `2009` | `please enter the correct verification code` | 身份验证器验证码不正确，请核对后重新输入 |
| `2010` | `please bind authenticator` | 请先绑定身份验证器后再操作 |
| `—` | `operation failed, please complete the verification first` | 请先完成前一步安全校验 |
| `—` | `failed to generate qr code` | 身份验证器二维码生成失败，请刷新重试 |

### 密码管理

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `2042` | `user does not exist.` | 账号不存在，请核对登录名 |
| `—` | `please refresh and try again.` | 页面窗口凭证不匹配（页面状态失效），请刷新后重试 |
| `—` | `failed to change password, passwords do not match` | 新密码与确认密码不一致 |
| `—` | `failed to change password, user does not exist` | 修改密码的目标账号不存在 |
| `—` | `failed to change password, old password is wrong` | 旧密码错误 |

### 子账号与权限

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `—` | `add '<username>' failed, record already exists` | 子账号名称已存在 |
| `—` | `edit '<username>' failed, record already exists` | 修改后的子账号名称与已有账号重复 |
| `—` | `no permission to update user` | 无权限修改该子账号 |
| `2042` | `user does not exist` | 子账号不存在 |
| `—` | `not allow edit the user` | 目标账号不是当前账号的子账号，无权操作 |
| `—` | `the current user type is not supported!` | 当前账号类型不支持子账号管理 |
| `—` | `employee illegal modification` | 当前账号类型无此操作权限 |
| `—` | `no permission` | 当前账号类型无此操作权限 |

### 批量付款与凭证

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `—` | `amount is not right` | 付款金额格式不正确 |
| `—` | `the current currency does not support` | 当前币种不支持批量付款 |
| `—` | `if the account amount is the same within five minutes, the transaction cannot be initiated` | 同一收款账号 5 分钟内不可发起第二笔相同金额的付款，请稍后重试 |
| `—` | `this area is not supported at this time` | 当前地区或币种暂不支持批量付款 |
| `—` | `please upload normal file format` | 批量付款文件仅支持 xlsx 格式 |
| `—` | `file reading exception` | 批量付款文件读取失败，请检查文件内容后重新上传 |
| `—` | `transaction does not exist` | 付款订单不存在，无法获取凭证 |

### 文件与导出中心

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `—` | `the file must be smaller than 200mb` | 文件大小不能超过 200MB |
| `—` | `upload file error, please put right usefor` | 文件上传失败，请确认文件类型与用途选择后重试 |
| `—` | `invalid taskid` | 导出任务不存在，请重新发起导出 |
| `—` | `data export does not exist` | 没有导出记录 |
| `—` | `data export is not complete, please try again later` | 导出任务尚未完成，请稍后重试 |
| `—` | `data export failed, unable to send download link email` | 导出失败，无法发送下载链接邮件，请重试 |
| `—` | `the maximum number of download link emails sent has reached 3 times` | 下载链接邮件发送次数已达上限（3 次） |

### 后台配置

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `—` | `the timezone is not supported` | 所选时区不受支持 |
| `—` | `unrecognised key` | 配置项不受支持，当前后台仅支持时区配置 |

### 其他

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `5003` | `system exception` | 后台临时异常，请稍后重试；持续出现请联系客服 |

## 收银台页面常见错误

本章错误提示出现在**收银台 / 收款链接 / 重定向支付页面**，面向**你的用户**（非 API 返回）。此类错误不返回独立错误码：JSON 响应中失败仅以 `status` 为 `0` 标识，`error` 保持 `00000000`（与成功值相同），提示文案在 `msg` 中；部分重定向页面直接输出纯文本。如持续出现，请携带提示内容与订单号联系 HaiPay 支持。

### 订单与订阅

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `—` | `orderNo does not legal` | 订单号格式校验失败 |
| `—` | `orderNo does not right` | 订单号格式校验失败 |
| `—` | `Order does not exist` | 订单不存在 |
| `—` | `order not exist` | 订单不存在 |
| `—` | `The order has expired, please place another order` | 订单已过期，请引导用户重新下单 |
| `—` | `The status is incorrect` | 提交的订单状态不合法（仅支持成功或失败） |
| `—` | `Result does not exist` | 查询订单时无法获取商户请求信息 |
| `—` | `The order is already in progress, please do not submit again` | 订单已提交处理中，请勿重复提交 |
| `—` | `subscription not found` | 订阅不存在 |
| `—` | `Invalid recurringInterval` | 订阅周期不合法（仅支持天、周、月、年） |

### 风控与汇率

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `—` | `Sorry, your region <region> is not supported at this time. <orderNo>` | 用户所在地区暂不支持交易（提示中会带上地区与订单号） |
| `—` | `The exchange rate conversion is wrong, please contact customer service` | 汇率转换异常，请联系客服 |

### 收款链接

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `—` | `The current link is invalid` | 收款链接已被禁用 |
| `—` | `Please add at least one currency configuration` | 所选币种缺少对应的业务配置 |
| `—` | `Sorry, this email provider is not supported. Please use a different email address.` | 邮箱服务商不受支持，请引导用户更换邮箱地址 |
| `—` | `Too many orders are created in a short time. Please try again later` | 短时间内创建订单过多触发频率限制（按链接与 IP 限流），请稍后重试 |
| `—` | `Currency is not supported` | 所选币种系统不支持 |
| `—` | `Limited capability, global checkout page is not activated. Please contact customer support.` | 全球收银台能力未开通，请联系客服 |

### 信息收集与 KYC

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `—` | `Email cannot be empty` | 特定支付场景要求收集邮箱 |
| `—` | `idCard cannot be empty` | 特定地区要求收集身份证号 |
| `—` | `user not found` | 未找到对应的 KYC 用户信息 |
| `—` | `Missing PDF configuration` | 生成 KYC 证明文件缺少模板配置，请联系客服 |
| `—` | `The data does not exist` | 按提供的姓名与证件号未找到用户信息 |
| `—` | `The name or ID number does not match the one you previously entered. Please re-enter.` | 姓名或证件号与此前填写不一致，请重新输入 |

### 信用卡

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `—` | `Enter a valid 14- to 19-digit card number.` | 银行卡号格式错误（应为 14-19 位数字） |
| `—` | `Please use a card from the brands displayed` | 卡 BIN 无法识别，请使用页面展示品牌的卡片 |

### 重定向页面

| 错误编码 | 错误提示 | 描述 |
| :- | :- | :- |
| `—` | `the url is not correct, try again !` | 重定向链接中的订单号非法 |
| `—` | `this website is not allow payment, please connect the customer service!` | 来源网站被禁止发起支付，请联系客服 |

## 订单失败原因（data.errorMsg）

在代收与代付订单查询接口的 `data` 中，除订单 `status`（数字）外还有 `errorMsg` 字段，表示**该笔订单的失败原因原文**。该字段描述订单自身的处理结果，可能包含银行或收款方返回的文案。

请根据 `data.status` 判断订单结果并做相应处理；如需协助，请携带 `orderNo` 联系 HaiPay 支持。

<Warning>
  请勿将 `data.errorMsg` 当作 API 调用结果。API 调用的成败由**顶层** `status` 与 `error` 决定；`data.errorMsg` 描述的是订单业务层的处理结果，二者属于不同层级。
</Warning>

| 失败原因原文 | 描述 |
| :- | :- |
| `Your account is restricted from ordering. Please contact customer support for help.` | 账户因入驻状态受限被限制下单，请联系客服 |
| `Your payment was declined due to security checks. Please try another card or payment method` | 交易被风控拦截，请更换卡片或支付方式 |
| `Your payment was declined due to security checks. Please try another card or payment method.(HP)` | 同上，带后缀的变体文案 |

## 相关主题

* [HaiPay 常见问题与排查](/docs/zh/guide/frequently_asked_question)
* [HaiPay 接口说明与公共规则](/docs/zh/guide/api_description_guide)
* [HaiPay 联调环境与请求地址](/docs/zh/guide/api_parameters_doc)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.