错误与速率限制

汇总 TronSave API 的速率限制（默认每秒 15 次请求）、统一响应结构、HTTP 状态码与错误码对照表，并给出 429 退避重试等常见错误的处理建议，助你构建健壮的集成。

每个 TronSave API 端点都共享相同的速率限制策略和错误响应结构。本页面对两者都进行了说明，方便你一次性构建健壮的重试和错误处理逻辑，并在所有调用中复用。

速率限制

大多数端点默认允许 每秒 15 次请求。

出售资源 端点被限制为 每秒 2–3 次请求。所有其他端点使用默认的每秒 15 次请求。

每个端点当前的限制都在其 API 参考页面中说明（例如，创建订单 和 预估 TRX 端点都注明 Rate limit: 15 requests per 1 second）。

当你超过限制时，API 会返回 HTTP 429：

{
    "error": true,
    "message": "Rate limit reached"
}

通过退避并重试来处理 429。简单的指数退避（例如先等待 1 秒，再 2 秒，然后 4 秒）通常足以保持在每秒预算之内。

响应结构

成功的响应使用统一的封装结构：error 为 false，message 为 "Success"，负载位于 data 之下。

{
    "error": false,
    "message": "Success",
    "data": {
        "orderId": "6818426a65fa8ea36d119d2c"
    }
}

错误响应返回非 2xx 的 HTTP 状态码。大多数应用层错误使用与成功响应相同的封装结构：error 为 true，可供程序识别的错误码嵌入在 message 中（例如 TSAS:106 API_KEY_REQUIRED），且 data 为 null：

{
    "error": true,
    "message": "TSAS:106 API_KEY_REQUIRED",
    "data": null
}

模式校验（schema validation）失败由 HTTP 层产生，使用不同的结构，并在 message 中指明出错的字段：

{
    "statusCode": 400,
    "code": "FST_ERR_VALIDATION",
    "error": "Bad Request",
    "message": "body must have required property 'receiver'"
}

错误码

下表列出了 API 中观察到的错误码，按 HTTP 状态分组。请使用 code（JSON 键）进行程序化处理——message 文本可能会发生变化。

HTTP	Code	Message
400	MISSING_PARAMS	请求主体中缺少某些参数
400	INVALID_PARAMS	某些参数无效
400	MIN_PRICE_INVALID	minPrice 低于系统的最低价格，或格式不正确。
400	INTERNAL_ACCOUNT_NOT_FOUND	内部账户不存在
400	INTERNAL_BALANCE_ACCOUNT_TOO_LOW	余额不足
400	CANNOT_FULFILLED	该订单要求立即完全匹配，但系统无法 100% 完成它。
400	MUST_BE_WAIT_PREVIOUS_ORDER_FILLED	系统中已存在一个具有相同参数的待处理订单。
400	PRICE_EXCEED_MAX_PRICE_REQUIRED	订单价格超过了可接受的最高价格。
401	API_KEY_REQUIRED	请求头中缺少 API 密钥
401	INVALID_API_KEY	API 密钥不正确
429	RATE_LIMIT	已达到速率限制

并非每个错误码都适用于每个端点。例如，CANNOT_FULFILLED 和 PRICE_EXCEED_MAX_PRICE_REQUIRED 仅在创建订单时返回。各个 API 参考页面会列出特定于每个端点的错误码。

错误负载示例

400: 请求错误

模式校验（必填字段缺失或无效——消息会指明该字段）：

{
    "statusCode": 400,
    "code": "FST_ERR_VALIDATION",
    "error": "Bad Request",
    "message": "body must have required property 'receiver'"
}

业务逻辑校验（由订单相关端点返回）使用标准封装结构：

{
    "error": true,
    "message": "TSAS:xxx INTERNAL_BALANCE_ACCOUNT_TOO_LOW",
    "data": null
}

401: 未授权

缺少 apikey 请求头：

{
    "error": true,
    "message": "TSAS:106 API_KEY_REQUIRED",
    "data": null
}

apikey 无效：

{
    "error": true,
    "message": "TSAS:107 INVALID_API_KEY",
    "data": null
}

旧版 v0 API 不包含 data 字段：{"error": true, "message": "TSAS:107 INVALID_API_KEY"}。

404: 未找到

路由或路径错误：

{
    "message": "Route POST:/v2/... not found",
    "error": "Not Found",
    "statusCode": 404
}

429: 请求过多

{
    "error": true,
    "message": "Rate limit reached"
}

处理常见情况

• 401（API_KEY_REQUIRED / INVALID_API_KEY） —— 检查 apikey 请求头是否存在且正确。参见 身份验证。

• INTERNAL_BALANCE_ACCOUNT_TOO_LOW —— 在创建订单之前为你的 内部账户 充值。

• CANNOT_FULFILLED —— 市场无法以请求的价格完全成交该订单。降低预期（例如启用 allowPartialFill）或调整 unitPrice。

• PRICE_EXCEED_MAX_PRICE_REQUIRED —— 预估价格高于你的 options.maxPriceAccepted。重试前请通过 预估 TRX 重新核对价格。

• 429（RATE_LIMIT） —— 退避并在你的每秒预算内重试。

后续步骤

• 身份验证 —— 如何获取并发送你的 API 密钥。

• API 参考 —— 各端点的参数和响应。