# Rate Limit

> URL: https://foura.ai/zh/docs/api/rate-limits
> Updated: 2026-11-06
> Index: https://foura.ai/llms.txt

每个 FourA API request 在到达引擎前都会通过三项检查：您个人方案的限制、平台针对所有流量的共享配额，以及平台针对您所调用 endpoint 的共享配额。每项检查都可以单独拒绝 request，且各自返回不同的响应 body。

## 按顺序排列的三项检查

1. **方案限制。** 您个人方案所允许的范围：包含哪些 endpoint 和参数、每个 endpoint 允许同时运行多少个 request、每分钟允许多少个、每天允许多少个浏览器 request，以及计费周期内可用的点数和带宽。
2. **全局平台限制。** 您所调用的 API 主机在该时刻正在处理的所有内容，无论流量流向哪个 endpoint。此处拒绝会报告 `"service": "api"`。
3. **单 endpoint 平台限制。** 您调用的 single、proxy 或 browser 服务上的流量。

系统首先判断您个人的方案，这种顺序属于协议规则而非实现细节。共享配额属于公共资源，因此平台注定要拒绝的 request 绝不能在被拒绝的过程中消耗这些配额。如果某个账户发送的量远超其方案允许范围，在该 request 触及任何人共享的资源之前就会被截断。

检查 2 和检查 3 统计的是 FourA 的总流量，而不是您的流量。来自这两项检查中任一处的拒绝，都应理解为“FourA 繁忙”，而不是“您发送了过多内容”。检查 1 仅针对您的个人账户，平台上其他任何操作都不会影响它。

来自任一共享检查的拒绝都会将准入时统计的全部额度返还给您的账户，无论是每分钟存储桶还是浏览器每日槽位，因为该 request 从未到达后端。它也不会计入 [Requests per minute](#requests-per-minute) 中描述的重试暂停：拒绝是因为 FourA 的容量不足，而不是您的方案限制。

`POST /api/auto/` 本身不占用槽位。它为您发起的 Single、Proxy 和 Browser 子调用与其他 request 一样需要通过全部三项检查，因此并行批量的 auto 调用会通过其子调用计入您的方案限制。（您的 request 计数和成功率会将 auto 调用本身计为一次；子调用显示为其尝试次数。）

## 方案限制

方案限制会返回一个 `X-FourA-Limit` header，指明具体是哪项限制拒绝了该调用。相同的代码也会出现在 body 的 `reason` 中，以便您无需读取 header 即可进行分支判断。每个方案限制的 body 都包含 `error`、`reason` 和 `documentation`；其余字段则取决于具体的限制项。

| `X-FourA-Limit` | 状态 | 耗尽项 |
|-----------------|--------|--------------|
| `plan_limit_feature` | 403 | 您调用的 endpoint，或 `exitCountries`、`exitState`、`exitCity`、`exitAsn` 或 `exitOs` 参数不在您的套餐中 |
| `plan_limit_premium` | 403 | `exitClass: premium` 不在您的套餐中，或者 Proxy request 指定了已无高级流量剩余的 [exit location](https://foura.ai/docs/api/endpoints#exit-location) |
| `plan_limit_concurrency` | 429 | 该 endpoint 上的并发 request 数 |
| `plan_limit_rate` | 429 | 该 endpoint 每分钟 request 数 |
| `plan_limit_browser_daily` | 429 | 当日 Browser request 数 |
| `plan_limit_credits` | 429 | 计费周期内的计费点数 |
| `plan_limit_bandwidth` | 429 | 计费周期内的带宽 |

每个限制的具体数值取决于您的套餐，[Usage & Limits](https://foura.ai/docs/dashboard/quota) 的 **Limits & Features** 标签页将其与您的实时用量并列展示。请勿对这些数值进行硬编码：每次拒绝都会附带触发拒绝的上限阈值。

被拒绝的 request 不会产生任何费用。其结果为 `rate_limit`，仅有 `success` 会被计费。

### 套餐未包含的 endpoint 或参数

返回 `plan_limit_feature` 的 403 状态码表示本次调用请求了套餐未包含的内容。该检查在计费统计前执行，因此被拒绝的调用不会影响您的速率限制或每日计数器。

```json
{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

如果计划不支持地理定位，而在 `POST /api/proxy/` 调用中设置了 `exitCountries`、`exitState`、`exitCity`、`exitAsn` 或 `exitOs`，将返回相同的代码和状态。`error` 字符串会指出具体的参数名称：

```json
{
  "error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

在不支持高级出口的套餐中，`exitClass: premium` 的结构与 `plan_limit_premium` 相同。包含高级出口但已用尽本周期高级流量的套餐不会被拒绝，除非 Proxy 请求指定了出口位置：请求将由标准池处理，且响应会返回 `exitClass: standard`。这两种情况都不会消耗高级出口。请参阅 [exitClass](https://foura.ai/docs/api/endpoints#exitclass)。

这两种 403 均不会设置 `Retry-After`。等待重试不会改变结果。

### 并发请求

并发按 endpoint 分别计算：您的套餐为 Single、Proxy 和 Browser 各自设定了独立上限。超出上限的请求将返回 429 状态码及 `Retry-After: 1`：

```json
{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}
```

`in_flight` 也会计入被拒绝的 request，因此其数值至少比 `limit` 多 1。

解决方法是限制自身的并发度，而不是更频繁地重试。收到 429 后立即重新发送同一批次，会导致其中的每个调用再次返回 429。完整实现模式请参阅 [Run Requests in Parallel](https://foura.ai/docs/how-to/run-requests-in-parallel)。

### 每分钟请求数

Single 和 Proxy 具有每分钟配额限制，基于滑动窗口分钟计算。仅计入已准入的 request：被拒绝的 request 会被扣除，因此持续略微超出配额的账户仍将获得足额配额的服务，而不会几乎全部被拒。

```json
{
  "error": "Rate limit reached: your plan allows 600 single requests per minute. Cool down and retry.",
  "reason": "plan_limit_rate",
  "documentation": "https://foura.ai/prices",
  "limit_per_minute": 600,
  "current_rate": 613,
  "retry_after_seconds": 17
}
```

`retry_after_seconds` 表示在不发送其他请求的情况下，距离允许下一个请求通过所需的等待时间：最少 1 秒，最多 120 秒。`Retry-After` header 携带相同的值。

若以快于该时间重试被拒绝的请求，则适用另一项单独规则。当在滑动窗口一分钟内被该配额拒绝的请求数超过配额的两倍时，调用将被拒绝并强制暂停 30 秒：

```json
{
  "error": "Rate limit cooldown: 1250 requests over your plan's 600 single requests per minute were refused in the last minute and kept arriving. Pause for 30 seconds.",
  "reason": "plan_limit_rate",
  "documentation": "https://foura.ai/prices",
  "limit_per_minute": 600,
  "current_rate": 540,
  "refused_last_minute": 1250,
  "cooldown": true,
  "retry_after_seconds": 30
}
```

暂停期间的拒绝不计入配额，因此随着当前这一分钟的过去，即使客户端持续重试，暂停也会自动结束。若要区分暂停与常规配额限制，请读取 `cooldown` 而非 `error` 文本。

### Browser 每日请求数

Browser 没有每分钟配额限制。其套餐限制为每天的 Browser 请求总数，自 UTC 零点开始计算，计量器会统计准入的每个 Browser 请求，而不仅仅是成功的请求。在零额度时因 FourA 端失败的 Browser 调用（例如 503 `Backend service unavailable`）会退还其每日名额。未被限流拒绝的 Browser 和 Auto 响应会在 `X-FourA-Browser-Used-Today` 和 `X-FourA-Browser-Limit-Per-Day` 响应头中携带计数与上限值：参见 [Response Headers](https://foura.ai/docs/api/response-headers)。

```json
{
  "error": "Daily browser limit reached: your plan allows 300 browser requests per day (resets at midnight UTC).",
  "reason": "plan_limit_browser_daily",
  "documentation": "https://foura.ai/prices",
  "limit_per_day": 300,
  "used_today": 301
}
```

此拒绝响应不包含 `retry_after_seconds` 和 `Retry-After` header，因为等待时间以小时计而非秒。请将其视为终止信号，并将下一次运行安排在 UTC 时间午夜。

### 计费周期内额度

仅计费额度计入统计，即仅包括成功的 request。当计费总额达到当前周期可用额度时，后续 request 将被拒绝，直到周期重置或购买更多额度。

```json
{
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z"
}
```

`hard_stop` 是本周期停止处理 request 的计费 credit 上限。直接从 body 中读取该值，而无需自行计算：它已包含您在套餐之外额外购买的 credit。

### 计费周期的带宽

带有带宽上限的套餐在当前周期的标准流量达到该上限后会拒绝 request。高级流量拥有独立配额，不计入此上限。购买的带宽与套餐包含的带宽计费规则相同，`error` 字符串标明的是您的实际可用量，而不仅是套餐本身包含的额度。

```json
{
  "error": "Bandwidth limit reached: 50 GB is available to you this billing period.",
  "reason": "plan_limit_bandwidth",
  "documentation": "https://foura.ai/prices",
  "used_bytes": 53687091200,
  "limit_bytes": 53687091200,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z"
}
```

对于这两种周期限制，`retry_after_seconds` 上限均为 24 小时；`resets_at` 则是周期重置的确切时刻。

### 方案限制字段

| 字段 | 类型 | 存在于 | 说明 |
|-------|------|-----------|-------------|
| `error` | string | 全部 | 可读消息，包含您受限的具体数值 |
| `reason` | string | 全部 | `plan_limit_` 加上限制名称。与 `X-FourA-Limit` 响应头的值相同。 |
| `documentation` | string | 全部 | 指向方案页面的链接 |
| `retry_after_seconds` | number | concurrency, rate, credits, bandwidth | 需要等待的时间。与 `Retry-After` 响应头的值相同。 |
| `limit` | number | concurrency | 该方案在对应 endpoint 上允许的并发 request 数 |
| `in_flight` | number | concurrency | 您的账户在对应 endpoint 上正在运行的 request 数，包含被拒绝的 request |
| `limit_per_minute` | number | rate | 该方案在对应 endpoint 上每分钟允许的 request 数 |
| `current_rate` | number | rate | 滑动窗口一分钟内统计的 request 数，包含被拒绝的 request |
| `refused_last_minute` | number | rate pause | 滑动窗口一分钟内因超出每分钟配额而被拒绝的 request 数。仅在 30 秒暂停时出现。 |
| `cooldown` | boolean | rate pause | 因重试过快触发 30 秒暂停时为 `true`。在普通的每分钟拒绝中不存在。 |
| `limit_per_day` | number | browser daily | 该方案每日允许的浏览器 request 数 |
| `used_today` | number | browser daily | 今日统计的浏览器 request 数，包含被拒绝的 request |
| `used` | number | credits | 本周期截至目前已计费的 credit 数 |
| `hard_stop` | number | credits | 本周期停止处理 request 的计费 credit 上限 |
| `used_bytes` | number | bandwidth | 本周期截至目前的标准流量，单位为字节。不包含 Premium 流量。 |
| `limit_bytes` | number | bandwidth | 本周期可用字节数 |
| `resets_at` | string | credits, bandwidth | 周期结束的 ISO 8601 时间戳 |

方案限制使用 `retry_after_seconds`。下方的平台限制使用 `retryAfter`。重试辅助函数需要同时读取两者，或者读取 `Retry-After` 响应头，方案限制会设置该响应头，503 `API key check temporarily unavailable` 也会设置（参见 [错误](https://foura.ai/docs/api/errors)）。

## 平台限制

平台检查会针对每个服务追踪两项指标，并针对所有服务总体追踪另一项指标：

- **Concurrency**：FourA 同时正在运行的 request 数量。
- **RPM**：FourA 在过去 60 秒内接收的 request 数量。

这两个计数器由使用该服务的所有用户共享。下方 response 中的 `current` 和 `limits` 描述的是平台状态，而非您的账户。如果您想查询自己的数值，请读取方案限制 response 中的 `in_flight`，或在 [控制台](https://foura.ai/dashboard)中打开 **Usage & Limits**。

### 429：超出 RPM

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": {
    "concurrency": 12,
    "rpm": 3000
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}
```

该服务在过去一分钟内已达到允许的请求上限。请等待 `retryAfter` 秒。

### 503: 超出并发限制

```json
{
  "error": "Service at capacity",
  "status": 503,
  "service": "proxy",
  "retryAfter": 2,
  "current": {
    "concurrency": 500,
    "rpm": 1200
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}
```

服务当前正在运行允许同时处理的最大 request 数量。通常会在数秒内恢复。

## 服务已禁用

当服务因维护而临时下线时，API 将返回 503 状态码及不同的错误信息：

```json
{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

这不是 rate limit。服务暂时不可用。请检查 `retryAfter` 的值，并在等待该秒数后重试。这通常会在数分钟内恢复。

两种 503 结构包含相同的键，因此请根据 `error` 字符串进行分支判断，切勿根据存在哪些字段来判断。`Service disabled` 表示维护，`Service at capacity` 表示并发。

在维护结构中，`current.concurrency` 和 `current.rpm` 始终为 `0`，表示请求在进行任何指标衡量前已被拒绝。

## 平台限制字段

| 字段 | 类型 | 说明 |
|-------|------|-------------|
| `error` | string | 人类可读的错误消息 |
| `status` | number | HTTP 状态码（429 或 503） |
| `service` | string | 拒绝调用的服务：single、proxy、browser 或 api |
| `retryAfter` | number | 重试前建议等待的秒数 |
| `current.concurrency` | number | 拒绝请求时，该服务在所有客户中正在运行的请求数 |
| `current.rpm` | number | 过去 60 秒内，该服务处理的所有客户的请求数 |
| `limits.maxConcurrency` | number | 该服务的共享并发配额 |
| `limits.maxRpm` | number | 该服务的共享每分钟配额 |

## 使用单个 Helper 处理所有拒绝

`Retry-After` 设置在值得等待的套餐限制上，`retry_after_seconds` 位于其响应体中，`retryAfter` 则位于平台响应体中。请按此顺序读取这三者，并针对无法通过等待解决的套餐限制终止操作：

```python
import time
import requests

# Plan limits that a short wait never clears.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def wait_seconds(resp, attempt):
    header = resp.headers.get("Retry-After")
    if header and header.isdigit():
        return int(header)
    try:
        body = resp.json()
    except ValueError:
        return 2 ** attempt
    return body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt

def fetch(url, api_key, max_retries=5):
    for attempt in range(max_retries):
        resp = requests.post(
            "https://eu.api.foura.ai/api/single/",
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            json={"method": "GET", "url": url},
        )

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"stopped by plan limit {limit}: {resp.json().get('error')}")

        if resp.status_code in (429, 503):
            time.sleep(wait_seconds(resp, attempt))
            continue

        return resp

    raise RuntimeError("Max retries exceeded")
```

每日配额需要数小时才能恢复，周期配额需要数天才能恢复，因此请将其视为完全停止而非短暂等待。如果需要计划下一次运行，请读取响应体中的 `resets_at`。

## 建议

- 限制在途请求数量，而不是重试被拒绝的批次。重试风暴会将单个 429 变成连续的大量 429。
- 优先读取 `X-FourA-Limit`。该字符串能直接指明限制属于您的账户还是平台，平台级拒绝绝不会设置此字段。
- 不要硬编码数值。每个方案限制响应都会包含触发拒绝的上限值，[使用量与限制](https://foura.ai/docs/dashboard/quota)会显示所有相关限制。
- 平台限制的 `retryAfter` 按类型固定：并发为 2 秒，RPM 为 5 秒，维护为 60 秒。
- 通过匹配 `error` 来区分两种 503 错误。两种响应格式均包含 `current` 和 `limits`，因此仅检查“这些字段是否存在”会将维护误判为并发问题。
- 带有 `X-FourA-Limit` 的 403 属于您的方案限制，与目标网站无关。目标网站从未作出响应。

## 代理端口有独立指标

以上内容均针对 JSON API。通过 `proxy.foura.ai` 发送的流量遵循另一组独立的方案指标，单位也有所不同：同时打开的隧道数、每分钟开启的隧道数，以及账单周期的标准流量。由于 `CONNECT` 没有可放置内容的响应体，这些拒绝会以带有 `X-Foura-Error` header 的 HTTP 状态返回，而不是 JSON 响应体。有关状态表，请参阅 [代理端口](https://foura.ai/docs/api/proxy-port#responses)；有关端口流量消耗哪个配额池，请参阅 [方案计量方式](https://foura.ai/docs/guides/plans-and-metering)。

## 相关内容

- [并行运行请求](https://foura.ai/docs/how-to/run-requests-in-parallel)：有界并发模式的完整实现
- [使用量与限制](https://foura.ai/docs/dashboard/quota)：对照实时使用量查看各项方案限制
- [API 端点](https://foura.ai/docs/api/endpoints)：完整参数参考
- [错误处理](https://foura.ai/docs/api/errors)：所有错误类型和响应
- [响应 Header](https://foura.ai/docs/api/response-headers)：`X-FourA-Limit`、`Retry-After` 及其他
- [故障排查](https://foura.ai/docs/troubleshooting/common-issues)：常见问题与解决方案
