> For the complete documentation index, see [llms.txt](https://docs.jgopay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.jgopay.com/jian-ti-zhong-wen/errors.md).

# 错误处理

## 错误响应格式

所有错误采用统一格式：

```json
{
  "status": "error",
  "error": "ERROR_CODE",
  "message": "Human-readable error message"
}
```

| 字段        | 类型     | 说明            |
| --------- | ------ | ------------- |
| `status`  | string | 固定为 `"error"` |
| `error`   | string | 机器可读的错误代码     |
| `message` | string | 人类可读的错误描述     |

## 错误代码

### 认证错误

| 代码                    | HTTP 状态码 | 说明                           |
| --------------------- | -------- | ---------------------------- |
| `UNAUTHORIZED`        | 401      | 缺少或无效的访问令牌                   |
| `TOKEN_EXPIRED`       | 401      | 访问令牌已过期 — 请重新获取              |
| `INVALID_CREDENTIALS` | 401      | `merchant_id` 或 `api_key` 无效 |
| `MERCHANT_DISABLED`   | 403      | 商户账户已停用                      |
| `MERCHANT_LOCKED`     | 403      | 商户账户已锁定                      |

### 校验错误

| 代码                         | HTTP 状态码 | 说明                                                                                                                                         |
| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `VALIDATION_ERROR`         | 400      | 一个或多个字段校验失败                                                                                                                                |
| `INVALID_AMOUNT`           | 400      | 金额超出允许范围                                                                                                                                   |
| `DUPLICATE_REFERENCE`      | 409      | `reference_id` 已被使用                                                                                                                        |
| `MISSING_PROVIDER_CHANNEL` | 400      | `BANK_TRANSFER` 未传 `metadata.provider_channel_id` — 见[支付方式](https://docs.jgopay.com/jian-ti-zhong-wen/pages/SbTu79bJ3Qq30bam3c80#fpx-银行代码) |
| `INVALID_PROVIDER_CHANNEL` | 400      | `provider_channel_id` 不在允许列表中                                                                                                              |

### 提现错误

| 代码                  | HTTP 状态码 | 说明                                                 |
| ------------------- | -------- | -------------------------------------------------- |
| `INVALID_AMOUNT`    | 400      | 提现金额超出 50.00 – 50,000.00 MYR 范围                    |
| `INVALID_BANK_CODE` | 400      | 不支持的银行代码。见[银行代码](/jian-ti-zhong-wen/bank-codes.md) |

### 频率限制

| 代码             | HTTP 状态码 | 说明                  |
| -------------- | -------- | ------------------- |
| `RATE_LIMITED` | 429      | 请求过于频繁 — 请放慢速度并延迟重试 |

429 响应包含 `Retry-After` 头（单位秒）。各接口限额和推荐的退避策略见[频率限制](/jian-ti-zhong-wen/rate-limiting.md)。

### 网关错误

| 代码                     | HTTP 状态码 | 说明       |
| ---------------------- | -------- | -------- |
| `NO_GATEWAY_AVAILABLE` | 503      | 该方式无可用网关 |
| `GATEWAY_ERROR`        | 502      | 上游网关返回错误 |
| `GATEWAY_TIMEOUT`      | 504      | 上游网关无响应  |

## 校验规则（MYR）

```json
{
  "status": "error",
  "error": "VALIDATION_ERROR",
  "message": "reference_id must contain only alphanumeric characters (a-z, A-Z, 0-9)"
}
```

| 校验项                            | 规则                       |
| ------------------------------ | ------------------------ |
| `reference_id`                 | 仅限字母和数字 — 不允许空格、连字符或特殊字符 |
| `amount`                       | 最多 2 位小数                 |
| `amount` 范围                    | 5 – 50,000 MYR           |
| `metadata.provider_channel_id` | `BANK_TRANSFER` 时必填      |

## 错误处理建议

### 推荐流程

```
1. 检查 HTTP 状态码
2. 解析错误响应体
3. 用 `error` 代码做程序化处理
4. 记录 `message` 便于排查
5. 向您的客户展示友好的提示信息
```

### 重试指引

| 错误代码                   | 可重试？ | 处理措施              |
| ---------------------- | ---- | ----------------- |
| `VALIDATION_ERROR`     | 否    | 修正请求参数            |
| `INVALID_AMOUNT`       | 否    | 调整金额              |
| `DUPLICATE_REFERENCE`  | 否    | 更换 `reference_id` |
| `UNAUTHORIZED`         | 否    | 重新认证              |
| `TOKEN_EXPIRED`        | 是    | 获取新令牌后重试          |
| `NO_GATEWAY_AVAILABLE` | 是    | 延迟后重试             |
| `GATEWAY_ERROR`        | 是    | 延迟后重试             |
| `GATEWAY_TIMEOUT`      | 是    | 延迟后重试             |
| `RATE_LIMITED`         | 是    | 等待后重试             |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.jgopay.com/jian-ti-zhong-wen/errors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.