错误与约定

本页是 TRONAgg API 如何报告失败、以及每个端点都遵循的横切规则的参考：错误信封、完整的错误代码目录、购买的幂等性、分页方式，以及你在每个响应中都会看到的单位与格式。

错误信封

错误使用标准 HTTP 状态码，外加一个带顶层 detail 的 JSON 请求体。大多数端点在 detail 中放一个结构化对象：一个机器可读的 error 代码、一个人类可读的 message，以及——对少数错误——额外的上下文字段。

{
  "detail": {
    "error": "insufficient_balance",
    "current_balance": 1200000,
    "required_amount": 3500000
  }
}

请基于 detail.error 分支处理；当存在 detail.message 时向用户展示它。

诚实的例外

少数响应不遵循带 error 的对象结构。请防御性处理——读取 detail，并：

纯字符串 detail。 某些响应将 detail 设为裸字符串而非对象。它们是：
- 任意 API key 端点上的 401——"API key required"、"Invalid API key" 或 "User not found"。
- GET /order/{id} 上的 404——"Order not found"（当订单存在但不属于你时也会返回）。
- URL 主机不是公网主机时 POST /webhooks 上的 400——例如 "Webhook URL must use a public host"、"Webhook URL must include a host"、"Webhook host could not be resolved"。
```
{ "detail": "Order not found" }
```
以 code 而非 error 为键的对象。 POST /buy 上的订单金额限制错误使用 code（外加 min / max）——见订单金额限制。
请求校验 422。 格式错误的请求体或超范围的查询参数（例如 resource_amount ≤ 0，或 page_size 超过 100）会被框架以 422 拒绝，并返回一个字段错误的 detail 数组。
```
{ "detail": [ { "loc": ["query", "resource_amount"], "msg": "...", "type": "..." } ] }
```

因此，健壮的客户端应检查 detail 的类型：对象 → 基于 detail.error 分支处理（回退到 detail.code）；字符串 → 视为人类可读的消息；数组 → 请求校验错误。

错误代码

编程式 API

`error` 代码	HTTP	端点	额外字段	触发时机
`unsupported_resource`	`400`	`GET /estimate`、`POST /buy`	—	`resource_type` 不是 `ENERGY`。
`invalid_duration`	`400`	`GET /estimate`、`POST /buy`	—	`duration` 不是 `1h`。
`invalid_idempotency_key`	`400`	`POST /buy`	—	`Idempotency-Key` 超过 128 个字符。
`insufficient_balance`	`400`	`POST /buy`	`current_balance`、`required_amount`	余额低于订单总额。此端点上没有 `message` 字段。
`validation_error`	`400`	`POST /buy`、`POST /webhooks`	`message`	购买校验被拒，或 Webhook URL 被拒（例如非 HTTPS）。
`invalid_cursor`	`400`	`GET /transactions`	`message`	`cursor` 值无法解析。
`duplicate_request`	`409`	`POST /buy`	—	具有相同 `Idempotency-Key` 的请求仍在处理中。
`not_found`	`404`	`DELETE /webhooks/{id}`、`POST /webhooks/{id}/test`	`message`	此账户没有该 Webhook。
`delivery_failed`	`502`	`POST /webhooks/{id}/test`	`message`	测试投递未成功。
`service_unavailable`	`503`	`GET /estimate`、`POST /buy`	`message`	能量购买暂时不可用。
`internal_error`	`500`	`POST /buy`	`message`	意外的服务端错误（已记录以便排查）。请稍后重试。

关于 POST /buy 上的 order_amount_below_minimum / order_amount_above_maximum 代码，见订单金额限制。

AutoEnergy

AutoEnergy 端点（/autoenergy/*）全部使用对象信封——{"error": <code>, "message": <text>}——并使用以下代码：

`error` 代码	HTTP	触发时机
`plan_not_found`	`400`	请求的套餐不存在。
`insufficient_balance`	`400`	余额过低，无法开始或继续订阅。（与 `POST /buy` 不同，此处带 `message`。）
`not_found`	`404`	此账户没有该订阅。
`address_busy`	`409`	该地址当前正在处理中；请稍后重试。
`address_exists`	`409`	已有活跃订阅覆盖该地址。
`not_reactivatable`	`409`	该订阅在当前状态下无法重新激活。
`not_deletable`	`409`	该订阅在当前状态下无法删除。
`invalid_address`	`422`	该地址不是有效的 TRON 地址。
`fulfiller_unavailable`	`502`	履约后端无法访问；请重试。
`autoenergy_temporarily_unavailable`	`503`	AutoEnergy 暂时不可用；请稍后重试。
`internal_error`	`500`	意外的服务端错误（已记录以便排查）。请稍后重试。

幂等性

POST /buy 是唯一涉及资金的写操作，因此它接受一个 Idempotency-Key 请求头来使重试安全：

发送任意**≤ 128 个字符**的唯一字符串（UUID 是不错的选择）。更长的 key 会返回 400 invalid_idempotency_key。
使用某个 key 的第一个请求会被处理；其响应会被缓存 24 小时，并对之后任何复用同一 key 的请求原样返回——因此网络重试绝不会下第二单。
如果在第一个仍在处理时到达一个重复请求，会返回 409 duplicate_request。请等待并重试；随后你将得到缓存的原始响应。
key 的作用域为每个账户。在两次确实不同的购买之间复用同一 key，会返回第一次购买的响应，而非新订单。

该请求头是可选的，但强烈建议任何自动化买家使用。

分页

存在三个列表端点，而且——由于历史原因——每个的分页方式都不同。请分别按各自的规则理解。

端点	请求参数	响应字段	分页方式
`GET /orders`	`page`（≥ 1）、`page_size`（1–100）	`orders`、`total`、`page`、`page_size`	基于页码，带完整 `total` 计数。
`GET /transactions`	`limit`（1–100）、`cursor`	`transactions`、`has_more`、`next_cursor`	基于游标。将上一次的 `next_cursor` 作为 `cursor` 传回以获取下一页；当 `has_more` 为 `false` 时停止。
`GET /deposits`	`limit`（1–100）、`offset`（≥ 0）	`deposits`、`has_more`	limit/offset。每页将 `offset` 前进 `limit`；当 `has_more` 为 `false` 时停止。

三者都按最新在前返回。/transactions 与 /deposits 上没有 total——用 has_more 来决定是否再取一页。

GET /orders 上的 `receiver_address` 过滤

可选的 receiver_address 查询参数是子串匹配，同时应用于每个订单的接收方和买家地址（不区分大小写）。部分值会匹配任何接收方或买家地址包含它的订单；完整的 34 位地址则表现为精确匹配。

单位与格式

SUN。 所有 *_sun 字段中的金额都是以 SUN 计的整数，SUN 是 TRX 的最小单位：1 TRX = 1,000,000 SUN。
小数金额是字符串。 面向用户的 TRX 金额（total_price_trx、amount_trx、balance_trx 等）被序列化为 JSON 字符串而非数字，以保持精确精度。请用 decimal 类型解析，绝不要用 float。
订单状态为大写。 订单的 status 是 PENDING、PROCESSING、AWAITING_PAYMENT、COMPLETED 或 FAILED 之一。COMPLETED 与 FAILED 为终态。
TRON 地址。 地址是以 T 开头、长度为 34 个字符的 base58 字符串。
时间戳。 时间字段（created_at、completed_at 等）是 UTC 的 ISO-8601。

订单金额限制

每个订单都有最小和最大资源数量。可从 GET /estimate 读取当前边界，它会在价格之外返回 min_amount 与 max_amount。

POST /buy 强制执行相同的边界。超范围的数量会返回 400，其结构化 detail——与其他购买错误不同——以 code（而非 error）为键，并携带 min / max：

{
  "detail": {
    "code": "order_amount_below_minimum",
    "message": "Order amount 500 is below the minimum (1000). Increase the amount or contact support.",
    "min": 1000,
    "max": 5000000
  }
}

这两个代码是 order_amount_below_minimum 和 order_amount_above_maximum。请先查 GET /estimate 以避免多一次往返。

下一步

身份验证——X-API-Key 请求头以及上文的 401 响应。
购买能量——大多数此类错误的来源购买端点。
Webhook 事件——轮询订单状态的推送替代方案。

错误信封​

诚实的例外​

错误代码​

编程式 API​

AutoEnergy​

幂等性​

分页​

GET /orders 上的 receiver_address 过滤​

单位与格式​

订单金额限制​

下一步​