# 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 官方文档](/getting-started/buy-energy-via-api-on-catfee/api-overview.md)

***

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.catfee.io/getting-started/faq.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.