# API常见问题

#### **1. 账户与权限相关问题**

**1.1 为什么我的 API 密钥无法使用？**

* **原因**：
  * API 密钥可能已被禁用或删除。
* **解决方案**：
  1. 登录 CatFee官网，检查您的 API 密钥状态是否有效。

**1.2 如何为 API 密钥启用仅特定 IP 访问？**

* **解决方案**： 在创建或编辑 API 密钥时，填写您想绑定的 IP 地址。这样，API 密钥仅允许来自该 IP 地址的请求，提升安全性。

***

#### **2. 签名与身份验证问题**

**2.1 为什么返回 `401 Unauthorized`？**

* **原因**：
  * `CF-ACCESS-KEY`、`CF-ACCESS-SIGN` 错误。
  * 签名生成不正确。
  * 时间戳偏差超过 5 秒。
* **解决方案**：
  1. 确保 `CF-ACCESS-KEY`、`CF-ACCESS-PASSPHRASE` 与创建 API 密钥时一致。
  2. 确保签名按照 CatFee 签名规则 生成，并验证生成逻辑。
  3. 确保 `CF-ACCESS-TIMESTAMP` 是标准的 UTC 时间戳，且与服务器时间偏差小于 5 秒。

**2.2 签名生成如何检查？**

* **解决方案**：
  1. 打印拼接的待签名字符串（`timestamp + method + requestPath`）。
  2. 对比生成的签名和本地手动计算的签名是否一致。
  3. 如果有疑问，可以使用 Postman 或 Curl 手动测试签名。

***

#### **3. 请求与响应问题**

**3.1 为什么返回 `400 Bad Request`？**

* **原因**：
  * 请求参数错误（如缺少必填字段或字段值不正确）。
  * 接口路径错误。
* **解决方案**：
  1. 检查接口文档，确保请求参数和路径准确。
  2. 验证请求头中的 `Content-Type` 是否设置为 `application/json`。
  3. 检查提交的数据格式是否为 JSON 格式。

**3.2 为什么返回 `429 Too Many Requests`？**

* **原因**：
  * 请求频率超过了 API 限制。
* **解决方案**：
  1. 阅读 API 文档，了解接口的速率限制（如每秒请求次数上限）。
  2. 在代码中实现请求节流（例如每秒发送的请求数控制在限制范围内）。
  3. 使用分布式请求时，确保所有请求的总频率不超过限制。

**3.3 为什么返回 `500 Internal Server Error`？**

* **原因**：
  * API 服务端可能存在临时问题。
* **解决方案**：
  1. 检查网络连接，确保请求已成功发送。
  2. 稍等几秒后重试。
  3. 如果问题持续，请联系 CatFee 技术支持。

***

#### **4. 特定接口问题**

**4.1 为什么无法成功下单？**

* **原因**：
  * 账户余额不足。
  * 订单参数不正确（如价格或数量）。
  * 账户未启用对应交易权限。
* **解决方案**：
  1. 检查账户余额是否充足。
  2. 确保订单参数（如数量、周期）符合最小下单规则（参考文档中 "创建订单" 部分）。

***

**4.2 如何确定购买能量成功到账**

1. **购买能量**之后记录返回值**id（支付哈希/订单 ID），其中**status=TRANSFER\_SUCCESS表示下单成功，通常下单成功之后6秒内能量到账
2. **通过订单详情`/v1/order/{id}`**查询该获取订单状态status，值通常如下

   * TRANSFER\_SUCCESS 下单成功
   * DELEGATE\_SUCCESS 代理成功
   * RECLAIM\_SUCCESS 回收成功

   当 `status` 为 `DELEGATE_SUCCESS` 时，表示能量交易已成功提交到波场区块链。注意：存在极小概率（约 0.1%）交易未能上链的情况
3. **链上确认状态**通过订单的详细信息**`/v1/order/{id}`**查询该获取订单确认状态**confirm\_status**

   当 `confirm_status` 为 `DELEGATION_CONFIRMED` 时，表示能量已100%成功发送并在链上确认

**4.3 为什么有些订单完成时间会比较长**

* 波场存在极小概率（约 0.1%）交易未能上链的情况，平台检测到交易未能上链会自动补发能量
* 当平台能量极度紧张的时候，平台发送能量会有一定延迟

#### **5. 开发与调试问题**

**5.1 如何处理超时问题？**

* **原因**：
  * 网络延迟或连接不稳定。
* **解决方案**：
  1. 设置较长的请求超时时间（如 `timeout=30`）。
  2. 对重要操作实现重试机制（如重试 2-3 次）。
  3. 检查本地网络与 CatFee API 的连通性。

**5.2 如何解析 API 响应？**

* **解决方案**： CatFee API 响应通常为 JSON 格式，结构如下：

  ```json
  json复制代码{
    "code": "0",
    "msg": "",
    "data": {
        "key": "value"
      }
  }
  ```

  * `code: 0` 表示成功，非 0 表示错误。
  * `data` 是返回的主要内容，通过解析 JSON 获取具体数据。

***

#### **6. 其他问题**

**6.1 为什么时间戳经常出错？**

* **原因**： 本地时间与 UTC 时间不同步。
* **解决方案**： 使用 Python 的 `datetime.utcnow()`

**6.2 如何处理 API 升级？**

* **解决方案**：
  1. 订阅 CatFee 的开发者公告，了解 API 的最新变化。
  2. 定期更新您的代码以适配新版本 API。
  3. 使用版本控制（如 `v1`）避免因升级导致兼容性问题。

***

#### **7. 联系支持**

如果您无法解决问题，请通过以下方式联系 CatFee 技术支持：

* 提交工单：CatFee支持中心
* 开发者文档：[API 官方文档](https://docs.catfee.io/getting-started/buy-energy-via-api-on-catfee/api-overview)

***

通过本 FAQ，希望能帮助您快速解决 CatFee API 使用中的常见问题！