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

# 错误处理

> 处理拒绝、限流和请求失败。

Provider 错误含 `code`、`message`、`retryable` 和可选 `retryAfter`（秒）。不同脚本构建间按 code 判断，不依赖 instanceof。本地精度工具、浏览器取消也可能抛出普通错误。

```ts theme={null}
export function walletErrorMessage(error: unknown): string {
  if (typeof error === 'object' && error !== null && 'code' in error) {
    switch (error.code) {
      case 'USER_REJECTED': return '已取消操作'
      case 'UNAUTHORIZED': return '请连接钱包并授权所需功能'
      case 'CONTEXT_CHANGED': return '账户或网络已变化，请重新确认'
      case 'RATE_LIMITED': return '请求频繁，请稍后重试'
      case 'TIMEOUT': return '请求超时，请先查询交易状态'
    }
  }
  return error instanceof Error ? error.message : '钱包请求失败'
}
```

| 错误码 | 处理 |
| - | - |
| USER\_REJECTED | 保留表单，等待用户决定 |
| UNAUTHORIZED | 用户操作时申请需要的权限 |
| WALLET\_LOCKED | 引导解锁 |
| CONTEXT\_CHANGED | 丢弃旧会话，重新读取状态 |
| UNSUPPORTED\_METHOD | 检查能力，禁用不支持的功能 |
| INVALID\_PARAMS | 修正地址、金额、精度等输入 |
| INSUFFICIENT\_FUNDS | 检查可用资产和 BTC 费用 |
| QUOTE\_EXPIRED | 获取新报价，让用户重新确认 |
| RATE\_LIMITED | 按 retryAfter 等待，限制并发 |
| TIMEOUT | 查询状态，避免重复提交 |
| NETWORK\_ERROR | 展示错误，允许刷新查询 |
| EXTENSION\_DISCONNECTED | 检查插件，重新连接 |
| INTERNAL\_ERROR | 展示错误，记录不含隐私的诊断信息 |

HTTP 429 通常是上游限流，SDK 无法消除服务端限流。仅对明确可重试的读取请求做有上限退避，避免多个组件同时轮询。

发送、发行、销毁、签名不自动重试。超时也可能已经提交，先核对钱包记录 / 协议状态，再由用户决定下一步。


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