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

# 速率限制

> Sorsa 的限制很简单：所有套餐每秒 20 次请求。本页介绍其工作方式及如何避免超限。

Sorsa 使用统一的速率限制，确保所有用户都能获得快速、稳定的服务。没有按端点划分的等级，也没有滚动时间窗口，只需围绕一个上限设计。

## 规则：每秒 20 次请求

每个 API 密钥最多 **每秒 20 次请求**。这是唯一的速率限制。没有端点级限制、15 分钟窗口、每小时重置，也没有套餐之间的差异。

使用同一密钥的所有工作进程都需要协调总请求速率。即使已在本地控制请求节奏，也应处理 `429` 响应。

需要了解的细节：

* 限制按 **API 密钥**计算，而非 IP 地址。多个密钥各有独立的每秒 20 次额度。
* **所有请求等量计数。** 一次 `/info` 调用和一次获取 100 条推文的 `/tweet-info-bulk` 调用，都算一次请求。
* **这不是滑动窗口。** 计数每秒重置。在 `T+0.00` 发送 20 次请求后，可在 `T+1.00` 再发送 20 次。

## 超过限制会怎样？

如果一秒内发送超过 20 次请求，超出的请求会返回 `429 Too Many Requests`。不会丢失数据，也不会处罚密钥。等到下一秒后重试即可。

响应不包含 `x-ratelimit-remaining` 或 `x-ratelimit-reset` 请求头。由于限制每秒重置，在响应头中追踪剩余额度会增加复杂度，而实际价值有限。

## 如何避免超限

大多数工作负载在正常运行时不会接近每秒 20 次。如果运行批量任务或处理大型数据集，可以采用以下两种简单方式。

### 方案 1：请求之间使用固定延迟

在单个串行工作进程中，每次收到响应后至少暂停 50ms，可限制发送速度。为了留出余量，可使用更长的暂停时间。多个进程共享密钥时，应使用统一的限流器；各自独立休眠 50ms 无法保证总速率不超过每秒 20 次。

**Python**

```python theme={null}
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.sorsa.io/v3"

usernames = ["elonmusk", "naval", "paulg", "vaborsh"]

for username in usernames:
    response = requests.get(
        f"{BASE_URL}/info",
        params={"username": username},
        headers={"ApiKey": API_KEY},
        timeout=30,
    )
    response.raise_for_status()
    print(response.json()["display_name"])
    time.sleep(0.05)  # 50ms between requests
```

**JavaScript**

```javascript theme={null}
const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.sorsa.io/v3";

const usernames = ["elonmusk", "naval", "paulg", "vaborsh"];

for (const username of usernames) {
  const res = await fetch(`${BASE_URL}/info?username=${username}`, {
    headers: { ApiKey: API_KEY },
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const data = await res.json();
  console.log(data.display_name);
  await new Promise((r) => setTimeout(r, 50)); // 50ms between requests
}
```

### 方案 2：收到 429 后重试

如果希望全速运行并在触及限制后处理，可以捕获 `429` 响应，短暂暂停后重试。

**Python**

```python theme={null}
import time
import requests

def fetch_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers, timeout=30)

        if response.status_code == 429:
            time.sleep(1)
            continue

        response.raise_for_status()
        return response.json()

    raise Exception("Rate limit: max retries exceeded")
```

**JavaScript**

```javascript theme={null}
async function fetchWithRetry(url, headers, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, { headers });

    if (res.status === 429) {
      await new Promise((r) => setTimeout(r, 1000));
      continue;
    }

    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json();
  }
  throw new Error("Rate limit: max retries exceeded");
}
```

实际使用中，结合两种方式效果最好：通过小延迟尽量避免 `429`，再用重试逻辑兜底。

## 批量端点降低高吞吐需求

优化速度之前，先检查批量端点能否减少总请求次数：

* `/info-batch`：一次最多获取 100 份用户资料
* `/tweet-info-bulk`：一次最多获取 100 条推文

对于速率限制和配额，一次批量请求与一次普通请求的计数相同。需要大量用户或推文数据时，批量获取通常比并行发送单条请求更高效。更多方式请参阅[优化 API 使用](https://docs.sorsa.io/zh-Hans/optimizing-api-usage)。

## 需要更高上限？

如果项目需要持续超过每秒 20 次的吞吐量，例如实时监测管道需要每秒 100 次以上，请通过[联系销售](https://api.sorsa.io/talk-to-sales)或 [Discord](https://discord.com/invite/uwAefKCj7X) 讨论专属基础设施和定制套餐。

## 后续步骤

* [分页](https://docs.sorsa.io/zh-Hans/pagination)：在速率限制内高效获取大规模数据集
* [错误码](https://docs.sorsa.io/zh-Hans/error-codes)：400、401、403、404、429 和 500 响应的完整参考