> For the complete documentation index, see [llms.txt](https://docs.catfee.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catfee.io/getting-started/buy-energy-via-api-on-catfee/api-error-codes.md).

# API 错误码与处理说明

CatFee API 错误码、触发原因、兼容说明与重试建议

本页说明 CatFee API 响应中的业务错误码、含义与处理建议。接入时请同时检查 HTTP 响应、业务 `code` 和订单状态。

{% hint style="info" %}
错误码按数字升序列在下方总表中。「业务类别」用于说明适用范围，具体以对应接口文档为准。标注「旧版」的条目用于兼容已有调用。
{% endhint %}

## 如何判断请求结果

CatFee API 的业务错误通常返回 **HTTP 200 + 非零整数 `code`**。不能仅凭 HTTP 200 判断业务成功，也不能把业务码 `201` 理解为 HTTP 201。

错误响应示例：

```json
{
  "code": 201,
  "msg": "Insufficient balance",
  "data": null
}
```

| 字段                   | 说明                                                          |
| -------------------- | ----------------------------------------------------------- |
| `code`               | 整数业务码。`0` 表示本次接口调用成功；所有非零码，包括尚未识别的码，都按失败处理。                 |
| `msg`                | 错误提示，文案可能随场景或版本变化。程序应按 `code` 分支，不要匹配提示文字。                  |
| `data`               | 成功响应的数据；错误时可能为 `null` 或省略，不应继续作为成功结果使用。                     |
| `sub_code`、`sub_msg` | 可选的补充信息。能量 API 使用下划线命名，不是 `subCode`、`subMsg`；它们不替代主 `code`。 |

客户端还需要处理非 200 响应、网络超时、空响应和非 JSON 正文。这些情况不能当成业务成功；即使错误正文无法解析，也应保留 HTTP 状态供排查。

**接口调用成功与订单执行成功需要分别判断。** 查询到失败订单时，查询接口仍可返回 `code=0`。创建订单成功或幂等返回原订单，也不表示能量已经到账；请继续检查 `data.status`、`data.confirm_status`，参见[购买能量](/api-reference/create-order.md)和[订单详情](/api-reference/order-detail.md)。

## 错误码总表

| code   | 业务类别            | 含义与常见原因                                         | 建议处理方式                                                    |
| ------ | --------------- | ----------------------------------------------- | --------------------------------------------------------- |
| `0`    | 通用              | 调用成功，包括成功返回已有的幂等结果                              | 正常处理返回数据；涉及订单时继续检查订单状态。                                   |
| `1`    | 通用              | 参数缺失、格式或范围不合法；部分接口也用此码表示鉴权信息有误                  | 检查参数、鉴权头、签名、时间戳及 IP 白名单，修正后再提交。                           |
| `2`    | 账户与认证           | 认证或访问被拒绝（旧版）                                    | 检查鉴权信息及操作权限，不要仅凭此码判定登录过期。                                 |
| `3`    | 通用              | 指定资源不存在（旧版）                                     | 检查资源 ID、账户和调用环境。                                          |
| `4`    | 通用              | 请求处理失败（旧版）                                      | 查询原操作结果；涉及下单或付款时不要直接重复提交。                                 |
| `5`    | 通用              | 当前状态不允许操作，或响应异常（旧版）                             | 查看错误提示并查询操作状态，无法确认时联系支持。                                  |
| `100`  | 账户与认证           | 缺少接口要求的身份凭据                                     | 补充 API 鉴权头，或完成该接口要求的登录。                                   |
| `101`  | 账户与认证           | 凭据无效、过期或签名验证失败                                  | 核对 Key、Secret、环境和签名；登录会话失效时重新登录。                          |
| `102`  | 账户与认证           | 没有操作目标资源的权限                                     | 检查资源归属和权限，不应因此自动退出登录。                                     |
| `103`  | 账户与认证           | 敏感操作缺少二步验证                                      | 按该接口要求提供二步验证码。                                            |
| `104`  | 账户与认证           | 二步验证失败                                          | 检查验证码及验证配置，避免连续提交错误验证码；不应自动退出登录。                          |
| `105`  | 账户与认证           | 二步验证服务暂不可用                                      | 稍后重新发起验证。                                                 |
| `106`  | 通用              | 请求或验证次数超限                                       | 降低频率，等待限制解除；若提供 `Retry-After`，按其提示等待。限流也可能通过 HTTP 429 返回。 |
| `107`  | 账户与认证           | 请求来源 IP 不在允许范围内                                 | 核对实际出口 IP 和 API IP 白名单。                                   |
| `108`  | 账户与认证           | 签名时间戳超出服务器当前时间 ±30 秒                            | 同步服务器时钟，重新生成 UTC 时间戳和签名。                                  |
| `109`  | 账户与认证           | 尚未配置操作所需的二步验证                                   | 先按账户要求启用二步验证。                                             |
| `110`  | 通用              | 当前业务状态不允许操作；旧接口或尚未细分的场景也可能用此码表示地址未激活、数量不符合条件    | 查询当前状态，调整请求或等待条件满足，避免原样立即重试。                              |
| `111`  | 通用              | 服务响应异常，暂时无法获取有效结果                               | 只读请求可延迟重试；涉及下单或付款时先核对原操作。                                 |
| `112`  | 通用              | 指定订单、地址、支付记录、入口、域名、套餐或节点不存在                     | 检查 ID、账户和调用环境，不要当成正常的空列表处理。                               |
| `113`  | 通用              | 服务暂不可用或暂无可用报价                                   | 只读请求可退避重试；下单先确认原请求结果，再按幂等规则处理。                            |
| `114`  | 通用              | 暂时无法确认操作的最终结果                                   | **先查询原订单和支付记录；涉及广播时按原交易哈希确认链上结果。不要直接重复付款、下单或广播。**         |
| `115`  | 账户与认证           | 邮箱等业务验证码无效或过期                                   | 重新获取并输入有效验证码；不表示当前登录会话失效。                                 |
| `116`  | 账户与认证           | 临时认证流程失效                                        | 重新开始本次认证流程，不要反复提交已失效的凭据。                                  |
| `201`  | 支付与余额           | 余额不足以支付所需费用                                     | 补足余额并核对原订单；重试同一笔购买时遵循该接口的幂等规则。                            |
| `202`  | 账户与认证           | 账户已禁用                                           | 停止重试并联系支持。                                                |
| `203`  | 支付与余额           | 支付或账户变动与已有记录冲突                                  | 核对支付记录和订单，不要换 ID 再付款；成功的幂等请求应返回 `0`。                      |
| `999`  | 通用              | 系统错误（旧版）                                        | 保留排查信息，先确认原操作结果，持续失败时联系支持。                                |
| `1003` | 时长租赁            | 能量接收地址的质押情况与请求数量不符合租赁限制                         | 检查接收地址的质押状态及购买数量，使用符合要求的地址或调整数量；仍无法满足条件时联系支持。             |
| `1004` | 时长租赁            | 接收地址未激活，且请求不允许自动激活                              | 先激活接收地址，或按接口要求允许自动激活并确认激活费用。                              |
| `1005` | 时长租赁            | 所需资源或对应价格提供方未配置租赁价格                             | 确认资源类型及价格配置；由相关代理商或平台补齐配置后重新获取报价。                         |
| `1006` | 时长租赁            | 实际订单金额（含激活费）超过已确认的金额上限                          | 重新获取报价并确认包含激活费的总金额；核对原批次或订单结果后再按接口规则提交。                   |
| `1101` | 波场伴侣（TRON Mate） | 地址已绑定托管服务，包括 Basic、Pro 或 Flash，不能重复添加           | 查询已有托管配置并使用或调整现有配置；需要切换服务时先处理原绑定。                         |
| `1102` | 波场伴侣（TRON Mate） | 托管地址尚未在 TRON 网络激活                               | 先激活地址，确认链上状态更新后再添加托管。                                     |
| `1103` | 波场伴侣（TRON Mate） | 地址的能量质押情况不符合当前托管模式的限制                           | 核对所选托管模式及地址质押状态，使用符合要求的地址或联系支持。                           |
| `1104` | 波场伴侣（TRON Mate） | 地址自身能量不足，不满足 Pro 托管当前模式的激活条件                    | 核对地址资源及配置数量，满足所选模式的能量要求后再激活；这不是账户余额不足。                    |
| `1105` | 波场伴侣（TRON Mate） | 尚未到达下一次订阅计费时间                                   | 等待下一计费时间，不要提前反复触发计费。                                      |
| `1201` | 无感能量            | 代理入口已禁用                                         | 确认入口状态，由有权限的账户启用后再请求。                                     |
| `1202` | 无感能量            | 广播交易的 owner 地址尚未绑定到入口                           | 核对交易 owner 和入口，将地址绑定到对应入口后再提交。                            |
| `1203` | 无感能量            | 绑定地址已禁用                                         | 检查绑定记录，由有权限的账户启用地址。                                       |
| `1204` | 无感能量            | 绑定地址已过期                                         | 更新绑定地址的有效期，确认生效后再请求。                                      |
| `1205` | 无感能量            | 绑定地址的可用配额不足                                     | 检查配额模式、已用及预占额度，按当前模式补充配额；充值账户余额不会自动增加地址配额。                |
| `1206` | 无感能量            | 处理期间配额模式或配置发生变化，当前请求无法预占额度                      | 刷新绑定地址配置并核对原请求结果，再按最新配置处理。                                |
| `1207` | 无感能量            | 当前配额模式仅支持平台认可的 USDT 交易                          | 核对交易类型、USDT 合约及所在网络，使用符合当前模式要求的交易。                        |
| `1208` | 无感能量            | 交易所需能量超过当前配额模式的单笔上限                             | 核对交易能量需求及模式限制，使用支持该需求的配置；增加总配额不能解除单笔限制。                   |
| `1209` | 无感能量            | 能量估算或购买数量超出允许范围                                 | 核对交易及能量需求，持续出现时联系支持，不要原样反复广播。                             |
| `1210` | 无感能量            | 绑定地址仍有交易处理中，暂不能执行当前配置操作                         | 等待在途交易处理完成，刷新绑定记录后再修改配置。                                  |
| `1211` | 无感能量            | 自定义域名已被占用                                       | 检查已有域名绑定，使用未被占用且有权管理的域名。                                  |
| `1212` | 无感能量            | 已达到可创建入口的数量上限                                   | 整理现有入口或联系支持，不要重复创建。                                       |
| `1213` | 无感能量            | 当前入口不是地址绑定模式，不能执行该地址管理操作                        | 确认目标入口，并按业务需要配置为 ADDRESS\_BOUND 模式后再操作。                   |
| `1214` | 无感能量            | 原始交易已过期                                         | 先按原交易哈希确认链上结果；确认需要重新发起时，重新构造并签名交易，不要继续广播已过期交易。            |
| `1215` | 无感能量            | 无限制配额模式不支持增加额度                                  | UNLIMITED 模式无需追加额度；核对当前配额模式和所调用的接口。                       |
| `1301` | 能量转租            | 实际能量接收地址的质押情况与请求数量不符合转租限制                       | 检查实际接收地址（包括转账备注指定的地址）及数量，调整后再按业务规则处理；不要直接重复转账。            |
| `1302` | 能量转租            | 配置的转租收款地址尚未激活                                   | 先激活收款地址，确认链上状态更新后再保存转租配置。                                 |
| `1303` | 能量转租            | 转租收款地址已存在，不能重复配置                                | 查询已有配置；仅修改自己有权限管理的配置，或使用其他符合要求的收款地址。                      |
| `1304` | 能量转租            | 会员已达到可配置转租地址的数量上限                               | 整理现有地址配置或联系支持，不要重复添加。                                     |
| `1401` | 速充（Flash）       | Flash 接收或托管地址尚未在 TRON 网络激活                      | 先激活地址，确认链上状态更新后再请求 Flash 服务。                              |
| `1402` | 速充（Flash）       | 地址仍有未完成的资源订单                                    | 查询并等待原订单完成，再发起新的请求，避免重复下单。                                |
| `1403` | 速充（Flash）       | 地址基础资源不足，不满足 Auto Flash 当前阈值、补充数量或代理限制；适用于能量和带宽 | 核对地址基础资源、触发阈值及补充数量，调整到符合要求后再提交；单纯充值账户余额不能解决。              |
| `1404` | 速充（Flash）       | 地址已绑定 Flash、Basic 或 Pro 等托管服务，不能重复添加            | 查询已有托管配置；需要切换服务时先处理原绑定。                                   |
| `1801` | 节点              | 已有待生效或尚未完成的订阅变更                                 | 查询并处理已有订阅变更，避免重复创建变更订单。                                   |
| `1802` | 节点              | 目标套餐的价格、总配额和速率指标同时有升有降，无法确定升级或降级方向              | 选择变更方向一致的套餐，无法确定时联系支持。                                    |
| `1803` | 节点              | 目标套餐的价格、总配额和速率与当前套餐一致                           | 继续使用当前套餐，或选择指标不同的套餐，不要重复提交相同变更。                           |
| `1804` | 节点              | 创建或访问节点需要有效订阅；访问时也可能是订阅记录不存在                    | 检查订阅及订单状态，完成订阅并确认生效后再操作。                                  |
| `1805` | 节点              | 节点已暂停                                           | 检查节点状态，由有权限的账户恢复后再请求。                                     |
| `1806` | 节点              | 节点订阅已过期                                         | 续费并确认订阅生效后再请求，单纯降低请求频率不能解决。                               |
| `1807` | 节点              | 当前订阅周期的总配额已耗尽                                   | 检查套餐及周期额度，等待额度刷新或按支持的方式升级套餐；短暂退避不能恢复总配额。                  |
| `2001` | 地址筛查            | 当前套餐无可用筛查配额                                     | 刷新套餐和额度，购买、续费或增加配额后再提交。                                   |
| `2101` | 兑换              | 兑换收款地址已经存在                                      | 查询并使用已有地址，避免重复添加。                                         |
| `2102` | 兑换              | 会员充值地址不能用作兑换收款地址                                | 更换符合要求的收款地址。                                              |
| `2103` | 兑换              | 当前订单不支持重新支付                                     | 查询原订单及付款状态，停止重复支付。                                        |
| `2104` | 兑换              | 当前订单不支持重试兑换                                     | 先确认原订单状态，再使用该业务允许的恢复操作。                                   |
| `9999` | 通用              | 系统错误，请求处理异常                                     | 只读请求可有限重试；下单、付款等先确认执行结果，持续失败时联系支持。                        |

收到未收录的非零码时，保留原始数字并按失败处理，不自动退出登录或重复提交下单、付款请求。错误文案仅供提示，不应作为程序判断条件。

## 无感能量与节点的响应格式

无感能量的业务错误码为 `1201–1215`，节点为 `1801–1807`。参数、认证、权限、余额等共性错误仍使用公共码，例如 `1`、`100`、`101`、`102`、`201`。API Key 无效不表示用户中心登录会话失效，不应自动退出登录。

* **应用 JSON API：** 业务错误通常保持 HTTP 200，通过整数 `code` 判断结果。地址管理查询不到绑定记录使用 `112`；广播鉴权发现交易 owner 未绑定属于 `1202`。
* **节点代理：** 已分类的访问拒绝保留 HTTP 403 或 429，同时在正文中返回业务码。HTTP 429 可能对应速率超限 `106`、订阅过期 `1806`、总配额耗尽 `1807`，也可能是订阅记录不存在 `1804`；应根据业务码处理，不能全部视为短期限流。
* **无感能量 HTTP 广播：** 失败响应保持 TRON 格式，通常为 HTTP 200、`result=false`、TRON `code` 和 `message`。此处的 `code` 不是本页业务码；节点原始错误使用节点枚举名称，未知枚举保留整数，原始 `message` 字节按 TRON 格式编码为十六进制。本地拒绝仍使用安全提示。
* **无感能量 gRPC 广播：** 失败也可能返回 HTTP 200、`grpc-status=0`，必须继续检查 `TransactionReturn.result`、`code` 和 `message`。节点明确拒绝时保留原始 `TransactionReturn`；业务码不能当作 TRON 枚举或 gRPC status。gRPC 查询的本地异常使用非 OK gRPC status。

广播结果未知或连接中断时，先按原交易哈希确认链上结果，再决定后续处理。TRON 广播被接受也不等于交易已在链上执行成功。广播接入说明见[无感能量 API 接入](/seamless-energy/api-integration.md)。

## 重试与结果确认

1. **先确认原操作结果。** 遇到 `114`、超时、断连或系统错误时，不能据此认定操作未发生。涉及订单或付款时，先查询原订单和支付记录；无法确认时联系支持。
2. **按错误原因处理。** 参数或鉴权错误应修正后再提交；权限不足、账户禁用或业务状态不允许时，不要原样反复请求。只读请求的临时故障可延迟重试，并限制次数和频率。
3. **遵循接口的幂等约定。** 对支持幂等的操作，重试应使用同一账户、原幂等编号和原业务参数，并重新生成时间戳和签名。不要为重试同一笔购买改用新编号；未确认幂等支持时，不要自动重新提交下单或付款请求。
4. **继续检查业务状态。** 返回已有订单或 `code=0` 不代表订单已支付成功或服务已交付，仍需检查相应业务状态。

签名规则见 [API概览](/getting-started/buy-energy-via-api-on-catfee/api-overview.md)，能量购买的幂等参数及示例见 [API支持幂等请求](/getting-started/api-supports-idempotent-requests.md)。

## 排查与反馈

联系支持时请提供调用环境、请求时间、HTTP 方法和路径、HTTP 状态、`code` / `msg`、订单 `id`、`client_order_id`，以及响应中如有的 `X-Request-ID`。请对请求信息脱敏，不要发送 API Secret、完整签名、Token、密码或验证码。

支持入口：[@CatFee\_James](https://t.me/CatFee_James)。