> For the complete documentation index, see [llms.txt](https://docs.tronsave.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tronsave.io/chinese/developers/errors-and-rate-limits.md).

# 错误与速率限制

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

## 速率限制

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

{% hint style="warning" %}
[出售资源](/chinese/developers/api-reference/sell-resources.md) 端点被限制为 **每秒 2–3 次请求**。所有其他端点使用默认的每秒 15 次请求。
{% endhint %}

每个端点当前的限制都在其 API 参考页面中说明（例如，[创建订单](/chinese/developers/api-reference/buy-resources/api-key/create-order.md) 和 [预估 TRX](/chinese/developers/api-reference/buy-resources/api-key/estimate-trx.md) 端点都注明 `Rate limit: 15 requests per 1 second`）。

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

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

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

## 响应结构

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

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

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

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

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

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

## 错误码

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

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

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

## 错误负载示例

{% tabs %}
{% tab title="400: 请求错误" %}
模式校验（必填字段缺失或无效——消息会指明该字段）：

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

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

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

{% endtab %}

{% tab title="401: 未授权" %}
缺少 `apikey` 请求头：

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

`apikey` 无效：

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

{% hint style="info" %}
旧版 v0 API 不包含 `data` 字段：`{"error": true, "message": "TSAS:107 INVALID_API_KEY"}`。
{% endhint %}
{% endtab %}

{% tab title="404: 未找到" %}
路由或路径错误：

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

{% endtab %}

{% tab title="429: 请求过多" %}

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

{% endtab %}
{% endtabs %}

## 处理常见情况

* **`401`（`API_KEY_REQUIRED` / `INVALID_API_KEY`）** —— 检查 `apikey` 请求头是否存在且正确。参见 [身份验证](/chinese/developers/authentication.md)。
* **`INTERNAL_BALANCE_ACCOUNT_TOO_LOW`** —— 在创建订单之前为你的 [内部账户](/chinese/concepts/glossary.md) 充值。
* **`CANNOT_FULFILLED`** —— 市场无法以请求的价格完全成交该订单。降低预期（例如启用 `allowPartialFill`）或调整 `unitPrice`。
* **`PRICE_EXCEED_MAX_PRICE_REQUIRED`** —— 预估价格高于你的 `options.maxPriceAccepted`。重试前请通过 [预估 TRX](/chinese/developers/api-reference/buy-resources/api-key/estimate-trx.md) 重新核对价格。
* **`429`（`RATE_LIMIT`）** —— 退避并在你的每秒预算内重试。

## 后续步骤

* [身份验证](/chinese/developers/authentication.md) —— 如何获取并发送你的 API 密钥。
* [API 参考](/chinese/developers/api-reference.md) —— 各端点的参数和响应。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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.tronsave.io/chinese/developers/errors-and-rate-limits.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.