> ## 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.