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

# 错误处理

> Waffo API 错误码分类与 Unknown Status 异常处理指南。

## 响应码

Waffo API 响应格式：

```json theme={null}
{
  "code": "0",
  "msg": "Success",
  "data": { ... }
}
```

* `code` 为 `"0"` 表示成功
* 失败时，`code` 为错误码字符串（例如 `"A0003"`、`"E0001"`）
* 响应字段名为 `msg`（不是 `message`）

## 错误码分类

| Prefix | Category               | Description         |
| ------ | ---------------------- | ------------------- |
| 0      | Success                | —                   |
| A      | Merchant error         | 参数错误、权限不足等          |
| B      | User error             | 余额不足、支付超时等          |
| C      | System error           | 渠道拒绝、系统错误等          |
| D      | Risk Control rejection | 交易被 Risk Control 拦截 |
| E      | Unknown error          | **关键：支付可能已成功**      |

完整错误码列表请参阅 [错误码速查](/docs/zh/developer-docs/tools-and-references/developer-tools/error-codes)。

## E0001 Unknown Status 处理

<Warning>
  **这是最关键的异常场景。** 当你遇到网络超时、连接中断，或服务端返回 `E0001` 时，支付状态未知。
</Warning>

### 原则

* **不要假设失败**：网络超时不代表支付没有成功
* **不要自动关闭订单**：支付可能已在 Channel 侧完成
* **不要创建新订单**：使用原始 `paymentRequestId` 进行查询

### SDK 中的错误类型

| Language | Unknown status error            | Client error       |
| -------- | ------------------------------- | ------------------ |
| Node.js  | `WaffoUnknownStatusError`       | `WaffoError`       |
| Java     | `WaffoUnknownStatusException`   | `WaffoException`   |
| Go       | `*core.WaffoUnknownStatusError` | `*core.WaffoError` |

<Note>
  SDK 只有两类错误。`WaffoUnknownStatusError`/`Exception` 表示支付可能已成功，而 `WaffoError`/`Exception` 表示客户端侧错误（配置、签名等）。
</Note>

### SDK 错误码

| Error code | Type          | Description          |
| ---------- | ------------- | -------------------- |
| S0001      | UnknownStatus | 网络错误（超时、连接失败）        |
| E0001      | UnknownStatus | 服务端返回 unknown status |
| S0002      | Error         | 公钥无效                 |
| S0003      | Error         | 签名失败                 |
| S0004      | Error         | 响应签名验签失败             |
| S0005      | Error         | 请求序列化失败              |
| S0007      | Error         | 私钥无效                 |

### 处理流程

```
Network timeout / E0001 / WaffoUnknownStatusError
    │
    ▼
Query using the original paymentRequestId
    │
    ├── PAY_SUCCESS found    → Update local status to success
    ├── ORDER_CLOSE found    → Update local status to failure
    └── Still unknown        → Wait for Webhook notification
```

### 代码示例

```typescript theme={null}
import { WaffoUnknownStatusError, WaffoError } from '@waffo/waffo-node';

try {
  const response = await waffo.order().create(params);
  if (response.isSuccess()) {
    // code === "0"，处理成功
  } else {
    // API 返回错误码（如 A0003），可以安全处理为失败
  }
} catch (error) {
  if (error instanceof WaffoUnknownStatusError) {
    // 重要：支付可能已成功！先查询再决定
    const inquiry = await waffo.order().inquiry({ paymentRequestId });
    if (inquiry.isSuccess()) {
      const status = inquiry.getData().orderStatus;
      await updateOrderStatus(paymentRequestId, status);
    }
    // 如果查询也失败，等待 Webhook
  } else if (error instanceof WaffoError) {
    // 客户端错误（配置、签名），修复后可重试
    console.error('Client error:', error.errorCode, error.message);
  }
}
```