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

# 错误处理

> 用 UQPAY Node.js SDK 处理 API 错误、配置重试并理解错误类型。

## 错误类型

所有 API 错误都会抛出继承自 `UQPayError` 的带类型错误类：

```ts theme={null}
import {
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  ServerError,
  NetworkError,
  SimulatorNotAvailableError,
} from '@uqpay/sdk'
```

每个错误对象暴露以下字段：

| 字段           | 类型       | 说明         |
| ------------ | -------- | ---------- |
| `message`    | `string` | 可读的错误描述    |
| `httpStatus` | `number` | HTTP 状态码   |
| `type`       | `string` | API 错误类型标识 |
| `code`       | `string` | API 错误码    |

## 捕获错误

```ts theme={null}
try {
  const account = await client.account.accounts.retrieve('acc-123')
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('账户未找到')
  } else if (err instanceof ValidationError) {
    console.log('请求参数错误：', err.message)
  } else if (err instanceof RateLimitError) {
    console.log('触发限流，SDK 会自动重试')
  } else if (err instanceof NetworkError) {
    console.log('网络错误：', err.message)
  } else if (err instanceof SimulatorNotAvailableError) {
    console.log('模拟器仅在沙盒可用')
  }
}
```

## 重试

SDK 会对服务端错误、限流和网络错误按指数退避自动重试。

全局或单次配置重试：

```ts theme={null}
// 全局——创建 client 时设置
const client = new UQPayClient({
  // ...
  maxRetries: 3,
})

// 单次请求——覆盖全局设置
await client.account.accounts.retrieve('acc-123', { maxRetries: 0 })
```