> ## 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 Python SDK 返回的带类型 API 和网络错误。

SDK会将API和传输层失败映射为带类型的异常。

```python theme={null}
from uqpay import (
    UQPayError,
    AuthenticationError,
    ForbiddenError,
    NotFoundError,
    ValidationError,
    RateLimitError,
    ServerError,
)

try:
    balance = client.banking.balances.retrieve("SGD")
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
except ForbiddenError as e:
    print(f"Access denied: {e.message}")
except NotFoundError as e:
    print(f"Not found: {e.message}")
except ValidationError as e:
    print(f"Validation error [{e.code}]: {e.message}")
except RateLimitError as e:
    print(f"Rate limited (HTTP {e.http_status})")
except ServerError as e:
    print(f"Server error: {e.message}")
except UQPayError as e:
    print(f"{e.type}: {e.message} (HTTP {e.http_status})")
```

每个`UQPayError`都包含`message`、`code`、`type`、`http_status`和`idempotency_key`。

客户端会按照`max_retries`配置重试暂时性失败。为单次调用设置`request_options={"max_retries": 0}`可禁用重试。