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

# 速率限制

> 请求速率限制、层级、消费上限，以及如何处理 429 响应。

## 速率限制层级

速率限制以 API 密钥为单位，使用 60 秒滑动窗口进行强制执行。每个密钥都有一个层级，用于决定其限制额度：

| 层级 | 每分钟请求数 (RPM) | 每分钟令牌数 (TPM) |
| - | - | - |
| 免费版（默认） | 60 | 100,000 |
| Starter | 300 | 500,000 |
| Pro | 1,000 | 2,000,000 |
| Enterprise | 5,000 | 10,000,000 |

所有新创建的 API 密钥都从**免费版**层级开始。

## 各模式限制

开销较大的模式设有更低的 RPM 上限，其数值按你所在层级的基础 RPM 按比例缩放：

| 模式 | 免费版 RPM | Starter RPM | Pro RPM | Enterprise RPM |
| - | - | - | - | - |
| Text / Code / Auto | 60 | 300 | 1,000 | 5,000 |
| Stealth | 30 | 150 | 500 | 2,500 |
| Image | 20 | 100 | 333 | 1,666 |
| Research | 15 | 75 | 250 | 1,250 |
| Video | 10 | 50 | 166 | 833 |

仪表盘会话的限制固定为 120 RPM。

## 如何提高你的限额

### 查看当前限额

```bash theme={null}
curl https://www.hitheo.ai/api/v1/rate-limits \
  -H "Authorization: Bearer theo_sk_..."
```

### 申请层级升级

```bash theme={null}
curl -X POST https://www.hitheo.ai/api/v1/rate-limits/request-increase \
  -H "Authorization: Bearer theo_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "requested_tier": "starter",
    "use_case": "Production chatbot serving 10K daily active users",
    "expected_volume": "~200 RPM peak, 50K requests/day"
  }'
```

申请将由 Theo 平台团队审核。获批后你会收到一个 `rate_limit.upgraded` webhook 通知。

## 信用额度余额

除了请求速率限制外，每个账户还拥有一个信用额度余额。当余额降至零时，后续请求会返回 `402 insufficient_credits`，直至你完成充值为止。

## 处理 429 响应

当触发速率限制时，API 会返回：

* **状态码 429**，并附带以下三种代码之一：
  * `rate_limit_exceeded` — 超出通用 RPM 限制
  * `mode_rate_limit_exceeded` — 超出各模式的 RPM 限制
  * `token_limit_exceeded` — 超出 TPM 限制
* **`Retry-After` 响应头** — 指示重试前需等待的秒数

SDK 会通过指数退避（可通过 `maxRetries` 配置）自动处理这一情况。

## 响应头

每个响应都包含反映你所在层级实际限额的速率限制响应头：

```
X-Ratelimit-Limit-Requests: 60
X-Ratelimit-Remaining-Requests: 47
X-Ratelimit-Reset-Requests: 58s
X-Ratelimit-Limit-Tokens: 100000
X-Ratelimit-Remaining-Tokens: 85000
X-Ratelimit-Reset-Tokens: 42s
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.