> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitflare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Apex 错误与速率限制

> OrbitFlare Apex 的全部错误：JSON-RPC 代码 -32001、-32029、-32602 和 -32603， 普通 HTTP 状态码、QUIC 准入码、速率限制，以及各自的处理方法。

## 已接受并不代表已上链

成功的响应表示 Apex 端点已持有您的交易，并正在将其竞速送达领导者，直到交易上链或其 blockhash 过期。这**并不**表示交易已上链。请在 Solana RPC 上使用 `getSignatureStatuses` 确认每一次发送。参见[最佳实践](/cn/apex/best-practices#确认每一次发送)。

Apex 按以下顺序检查交易：API 密钥、速率限制、交易有效性和大小，最后是小费。第一个未通过的检查决定返回的错误。在所有检查通过之前，交易不会发送到任何地方，因此被拒绝的交易不产生任何费用。

## JSON-RPC 错误

| 代码       | 含义                               | 处理方法                               |
| -------- | -------------------------------- | ---------------------------------- |
| `-32001` | 未授权。API 密钥缺失或无效                  | 检查 `x-api-key` 请求头或 `?api-key=` 参数 |
| `-32029` | 已被限速。您的密钥超出了每秒限制                 | 短暂退避后重试。平滑突发流量                     |
| `-32602` | 交易或小费无效。消息会说明哪项未通过，小费不足时还会注明您的下限 | 修正交易。重试相同的字节仍会失败                   |
| `-32603` | 繁忙。端点正在卸载负载                      | 短暂延迟后重试，或切换到另一个 Apex 端点            |

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "..."
  }
}
```

## 普通 HTTP 错误

在 `/send` 和 `/send-bin` 上，成功时返回 HTTP `200` 和 `{"signature": "..."}`。`/send-batch` 返回 `200` 和 `{"attempted": n, "accepted": n, "rejected": n, "results": [...]}`，其中每个结果按帧顺序排列，要么是 `{"signature": "..."}`，要么是 `{"error": "<label>", "message": "..."}`。`/send-bundle` 返回 `200` 和 `{"bundle_id": "...", "signatures": ["...", "..."]}`。

错误为 JSON 格式，包含一个机器可读的标签和一条人类可读的消息：

```json theme={null}
{ "error": "<label>", "message": "..." }
```

| 状态码   | 含义            | 标签                                                                                                                                                  |
| ----- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` | 未授权           | `unauthorized`                                                                                                                                      |
| `429` | 已被限速          | `rate_limited`                                                                                                                                      |
| `400` | 请求、交易或小费无效    | `invalid`, `malformed`, `no_signatures`, `no_tip`, `below_floor`, `multiple_tips`, `tip_not_static`, `tip_source_not_signer`, `too_large`, `bundle` |
| `408` | 请求正文未在 2 秒内到达 | `timeout`                                                                                                                                           |
| `413` | 请求体过大         | `too_large`                                                                                                                                         |
| `503` | 繁忙            | `busy`                                                                                                                                              |

<Note>
  请先根据 HTTP 状态码进行分支处理。它是接口约定中稳定的部分。对于 `400` 下您不认识的标签，请按“修正交易”处理。
</Note>

只要请求本身格式正确，`/send-batch` 就会返回 `200`，并在 `results` 中分别报告每一帧的结果。请检查 `rejected` 和每个条目，而不要只看状态码。参见 [POST /send-batch](/cn/apex/sending-transactions#post-/send-batch)。

`bundle` 标签（HTTP `400`）表示[捆绑包](/cn/apex/bundles)被整体拒绝：成员超过 4 个、存在重复成员、此密钥或端点不支持捆绑包，或者区块引擎拒绝了它。单个成员的问题仍使用各自的标签。超过 1232 字节的成员会返回 `malformed`，消息中会指明 1232 字节的限制；有两个成员带小费时返回 `multiple_tips`；没有成员带小费时返回 `no_tip`。

### 小费错误详解

| 标签                      | 问题所在                             | 修复方法                                    |
| ----------------------- | -------------------------------- | --------------------------------------- |
| `no_tip`                | 没有向已公布小费账户转账的顶层 SystemProgram 指令 | 添加[小费指令](/cn/apex/tips)。通过 CPI 进行的转账不算数 |
| `below_floor`           | 小费低于您所在等级的下限。消息中会注明下限            | 将小费提高到不低于下限                             |
| `multiple_tips`         | 存在多笔小费转账                         | 只保留一笔                                   |
| `tip_not_static`        | 小费账户是通过地址查找表加载的                  | 将小费账户放入静态账户密钥中                          |
| `tip_source_not_signer` | 支付小费的账户没有签名                      | 由签名者为小费出资                               |

## QUIC 准入码

双向 QUIC 流会返回一个准入码。单向流不返回任何内容，因此在集成阶段请使用双向流。

| 代码  | 名称               | Rust `AdmissionCode` | 对应的 JSON-RPC |
| --- | ---------------- | -------------------- | ------------ |
| `0` | ok               | `Ok`                 | result       |
| `1` | unauthorized     | `Unauthorized`       | `-32001`     |
| `2` | rate limited     | `RateLimited`        | `-32029`     |
| `3` | invalid          | `Invalid`            | `-32602`     |
| `4` | no tip           | `NoTip`              | `-32602`     |
| `5` | below floor      | `BelowFloor`         | `-32602`     |
| `6` | busy             | `Busy`               | `-32603`     |
| `7` | malformed packet | `MalformedPacket`    | 无            |

如果 QUIC **握手**本身被拒绝，连接会以应用层错误 `1`（无客户端证书）、`2`（未知密钥）或 `3`（连接数过多）关闭。参见[身份验证](/cn/apex/authentication#quic-客户端证书)。

在 Rust 客户端中，`send_transaction_with_response` 会将拒绝转换为 `Error::Rejected { code, message }`，超过 4096 字节的交易会在发送任何内容之前在本地以 `Error::TooLarge` 失败。

## 哪些错误可以重试

| 错误                      | 是否重试？                     |
| ----------------------- | ------------------------- |
| 已被限速（`-32029`、`429`）    | 是，短暂退避后重试                 |
| 繁忙（`-32603`、`503`）      | 是，短暂延迟后重试，或改用另一个 Apex 端点  |
| 收到响应前发生网络错误或超时          | 是。端点按签名去重，因此重新发送同一笔交易是安全的 |
| 交易或小费无效（`-32602`、`400`） | 否。请重新构建交易                 |
| 未授权（`-32001`、`401`）     | 否。请修正密钥                   |

您无需重新发送**已接受**的交易。Apex 已经在重试，直到它上链或 blockhash 过期。如果届时仍未上链，请使用新的 blockhash 重新构建，并发送新交易。

## 速率限制

速率限制**按 API 密钥**计算，并由密钥的**等级**决定。该限制统计所有传输方式上每秒的交易数：JSON-RPC、HTTP 路由和 QUIC 共用同一额度，批量请求中的每一帧计为一笔交易。

超出限制时，您会收到 `-32029`、HTTP `429` 或准入码 `2`。被拒绝的交易不会进入队列，因此如果它仍然重要，请稍后重新发送。

您所在等级的限制和小费下限显示在 [OrbitFlare 控制台](https://orbitflare.com/dashboard)的 **Dashboard > Apex** 下，位于密钥旁边。如需提高限制，请通过 [Discord](https://discord.gg/orbitflare) 联系团队。

## 限制一览

| 限制         | 值                                                         |
| ---------- | --------------------------------------------------------- |
| 交易大小       | Legacy 和 v0：1232 字节。[v1](/cn/apex/transaction-v1)：4096 字节 |
| 批量大小       | 每个 `/send-batch` 请求 16 笔交易                                |
| 捆绑包大小      | 1 到 4 笔交易，每笔 1232 字节                                      |
| QUIC 数据包大小 | 4160 字节                                                   |
| QUIC 连接数   | 每个 API 密钥 128 个，每个地址 64 个                                 |
| QUIC 空闲超时  | 30 秒。Rust 客户端每秒 ping 一次                                   |
| 连接数        | 每个进程和每个 Apex 端点一个 QUIC 客户端即可。各个流在其上多路复用                   |