# Лимиты запросов

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

Каждый запрос к FourA API проходит три проверки, прежде чем попасть в движок: лимиты вашего тарифного плана, затем общий лимит платформы для всего трафика и затем общий лимит платформы для вызванного endpoint. Каждая проверка может отклонить запрос самостоятельно, и каждая возвращает свое тело ответа.

## Три проверки по порядку

1. **Лимиты плана.** Разрешения вашего тарифа: доступные endpoint и параметры, число одновременных запросов на endpoint, число запросов в минуту, лимит браузерных запросов в день, а также доступные кредиты и пропускная способность в расчетном периоде.
2. **Глобальный лимит платформы.** Суммарная нагрузка на хост API в текущий момент, независимо от целевого endpoint. Отказ на этом этапе возвращает `"service": "api"`.
3. **Лимит платформы на endpoint.** Нагрузка на вызванный сервис: single, proxy или browser.

Ваш тариф проверяется первым, и этот порядок зафиксирован как контракт, а не деталь реализации. Общие ресурсы платформы едины для всех, поэтому запрос, который заведомо будет отклонен, не должен расходовать их перед отказом. Аккаунт, отправляющий больше разрешенного тарифом, блокируется до того, как затронет ресурсы других пользователей.

Проверки 2 и 3 учитывают общий трафик FourA, а не ваш. Отказ на любом из этих этапов означает "FourA перегружен", а не "вы отправили слишком много". Проверка 1 относится только к вашему аккаунту, и другие события на платформе на нее не влияют.

Отказ на любой из общих проверок возвращает вашему аккаунту все списанные квоты, включая минутный лимит и дневной слот браузера, так как запрос не дошел до бэкенда. Он также не учитывается в паузе повторных попыток, описанной в разделе [Requests per minute](#requests-per-minute): отказ произошел из-за емкости FourA, а не ограничений вашего плана.

`POST /api/auto/` не занимает отдельного слота. Вложенные вызовы Single, Proxy и Browser проходят все три проверки как стандартные запросы, поэтому параллельный пакет вызовов auto расходует лимиты плана через свои подзапросы. (Счетчики запросов и показатель успешности учитывают сам вызов auto один раз, а подзапросы отображаются как его попытки.)

## Лимиты плана

При срабатывании лимита плана возвращается заголовок `X-FourA-Limit` с кодом сработавшего ограничения. Этот же код передается в теле ответа в поле `reason`, что позволяет обрабатывать ветвление логики без чтения заголовков. Каждое тело ответа при превышении лимита содержит поля `error`, `reason` и `documentation`; состав остальных полей зависит от конкретного лимита.

| `X-FourA-Limit` | Статус | Что исчерпано |
|-----------------|--------|--------------|
| `plan_limit_feature` | 403 | Вызванный endpoint или параметр `exitCountries`, `exitState`, `exitCity`, `exitAsn` либо `exitOs` не входит в ваш тарифный план |
| `plan_limit_premium` | 403 | `exitClass: premium` не входит в ваш тарифный план, или запрос к Proxy указывает [exit location](https://foura.ai/docs/api/endpoints#exit-location) при исчерпанном премиум-трафике |
| `plan_limit_concurrency` | 429 | Одновременные запросы к этому endpoint |
| `plan_limit_rate` | 429 | Запросы в минуту к этому endpoint |
| `plan_limit_browser_daily` | 429 | Запросы browser на сегодня |
| `plan_limit_credits` | 429 | Оплачиваемые кредиты за расчетный период |
| `plan_limit_bandwidth` | 429 | Пропускная способность за расчетный период |

Значения каждого лимита определяются вашим тарифным планом, и вкладка **Limits & Features** в разделе [Usage & Limits](https://foura.ai/docs/dashboard/quota) отображает их рядом с текущим расходом. Не хардкодьте их: каждый отказ содержит лимит, из-за которого он произошел.

Отклоненный запрос ничего не расходует. Результат равен `rate_limit`, а тарифицируется только `success`.

### Endpoint или параметр не входит в тарифный план

Ответ 403 с кодом `plan_limit_feature` означает, что в запросе запрошено то, что не включено в тарифный план. Проверка выполняется до любого подсчета, поэтому отклоненный вызов не влияет на счетчики rate limit или дневного расхода.

```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"
}
```

`plan_limit_premium` имеет тот же формат для `exitClass: 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`.

Решение заключается в ограничении собственного параллелизма, а не в увеличении числа повторных попыток. Ответ 429 при немедленной повторной отправке того же пакета вызовет еще один 429 для каждого вызова внутри него. См. [Run Requests in Parallel](https://foura.ai/docs/how-to/run-requests-in-parallel) для готового примера реализации.

### Количество request в минуту

Для Single и Proxy действует лимит в минуту, измеряемый за скользящую минуту. В нем учитываются только принятые requests: отклоненный 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` показывает время до момента, когда будет разрешен еще один request, если между ними ничего не отправлять: от 1 до 120 секунд. header `Retry-After` содержит то же значение.

Для повторной отправки отклоненных запросов раньше этого срока действует отдельное правило. Когда число отклоненных в рамках этого лимита запросов за скользящую минуту превышает лимит более чем в два раза, вызов отклоняется с паузой в 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 requests в день

У Browser нет поминутного лимита. Лимит тарифа представляет собой количество browser requests в день, отсчитываемое с полуночи UTC, при этом счетчик учитывает каждый принятый browser request, а не только успешные. Вызов Browser, завершившийся ошибкой на стороне FourA при нулевом списании кредитов, например 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`, так как ожидание измеряется часами, а не секундами. Считайте это сигналом к остановке и запланируйте следующий запуск на полночь по UTC.

### Кредиты на расчетный период

Учитываются только оплачиваемые кредиты, то есть только успешные запросы. Когда оплаченная сумма достигает лимита кредитов, доступных вам в этом периоде, дальнейшие запросы отклоняются до сброса периода или покупки дополнительных кредитов.

```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`, это количество тарифицируемых кредитов, при достижении которого запросы в этом периоде прекращаются. Считывайте его из body, а не вычисляйте: оно уже включает все кредиты, купленные дополнительно к тарифу.

### Трафик за расчетный период

Тарифные планы с лимитом трафика отклоняют запросы, как только стандартный трафик за текущий период достигает этого значения. Для премиум-трафика предусмотрен отдельный лимит, и он не учитывается в этом ограничении. Купленный трафик учитывается так же, как и включенный в тариф, а строка `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 |
| `in_flight` | number | concurrency | Запросы к этому endpoint, выполняемые для вашего аккаунта, включая отклоненный |
| `limit_per_minute` | number | rate | Допустимое тарифным планом число запросов в минуту к этому endpoint |
| `current_rate` | number | rate | Запросы, учтенные за скользящую минуту, включая отклоненный |
| `refused_last_minute` | number | rate pause | Запросы, отклоненные поминутным лимитом за скользящую минуту. Только при 30-секундной паузе. |
| `cooldown` | boolean | rate pause | `true` при 30-секундной паузе из-за слишком частых повторных попыток. Отсутствует при обычном поминутном отказе. |
| `limit_per_day` | number | browser daily | Допустимое тарифным планом число browser requests в день |
| `used_today` | number | browser daily | Browser requests, учтенные за сегодня, включая отклоненный |
| `used` | number | credits | Израсходованные тарифицируемые кредиты за текущий период |
| `hard_stop` | number | credits | Объем тарифицируемых кредитов, при котором запросы блокируются в текущем периоде |
| `used_bytes` | number | bandwidth | Стандартный трафик за текущий период, в байтах. Премиум-трафик не включен. |
| `limit_bytes` | number | bandwidth | Доступный объем байтов в текущем периоде |
| `resets_at` | string | credits, bandwidth | Метка времени окончания периода в формате ISO 8601 |

Лимиты тарифного плана используют `retry_after_seconds`. Приведенные ниже лимиты платформы используют `retryAfter`. Обработчик повторных попыток должен считывать оба поля или проверять заголовок `Retry-After`, который выставляется как лимитами тарифного плана, так и ошибкой 503 `API key check temporarily unavailable` (см. [Errors](https://foura.ai/docs/api/errors)).

## Лимиты платформы

Проверки платформы отслеживают два показателя для каждого сервиса и еще один общий для всех:

- **Concurrency**: сколько запросов FourA выполняет одновременно.
- **RPM**: сколько запросов FourA приняла за последние 60 секунд.

Оба счетчика являются общими для всех пользователей сервиса. Значения `current` и `limits` в приведенных ниже ответах описывают состояние платформы, а не вашего аккаунта. Чтобы узнать свои показатели, считайте `in_flight` из ответа с лимитом тарифного плана или откройте раздел **Usage & Limits** в [панели управления](https://foura.ai/dashboard).

### 429: Превышен RPM

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

Сервис исчерпал лимит допустимых request за последнюю минуту. Подождите `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 | Общий минутный лимит запросов сервиса |

## Обработка каждого отказа с помощью одного хелпера

`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 во множество.
- Сначала проверяйте `X-FourA-Limit`. Этот заголовок одной строкой сообщает, принадлежит ли лимит вам или платформе, и отказы платформы его не выставляют.
- Не хардкодьте числа. Каждый ответ с превышением лимита тарифа содержит текущий потолок, из-за которого произошел отказ, а страница [Usage & Limits](https://foura.ai/docs/dashboard/quota) показывает их все.
- Значение `retryAfter` при лимитах платформы фиксировано по типу: 2 секунды для конкурентности, 5 для RPM, 60 для обслуживания.
- Сопоставляйте значение `error`, чтобы различать два типа ошибок 503. Обе структуры содержат `current` и `limits`, поэтому простая проверка наличия этих полей примет техническое обслуживание за проблему с конкурентностью.
- Ошибка 403 с `X-FourA-Limit` относится к вашему тарифу, а не к целевому сайту. Целевой сайт вообще не отвечал.

## Порт прокси имеет собственные ограничения

Все вышеперечисленное относится к JSON API. Трафик, отправляемый через `proxy.foura.ai`, регулируется отдельным набором лимитов тарифа в других единицах: одновременно открытые туннели, открытия туннелей в минуту и стандартный трафик за расчетный период. Эти отказы возвращаются в виде HTTP-статуса с заголовком `X-Foura-Error`, а не в виде тела JSON, так как у `CONNECT` нет тела для его размещения. Смотрите [Proxy Port](https://foura.ai/docs/api/proxy-port#responses) для таблицы статусов и [How Your Plan Is Metered](https://foura.ai/docs/guides/plans-and-metering), чтобы узнать, из какого пула списываются гигабайты порта.

## Связанные разделы

- [Run Requests in Parallel](https://foura.ai/docs/how-to/run-requests-in-parallel): готовый шаблон с ограничением параллелизма
- [Usage & Limits](https://foura.ai/docs/dashboard/quota): все лимиты тарифа рядом с вашим текущим использованием
- [API Endpoints](https://foura.ai/docs/api/endpoints): полный справочник по параметрам
- [Error Handling](https://foura.ai/docs/api/errors): все типы ошибок и ответов
- [Response Headers](https://foura.ai/docs/api/response-headers): `X-FourA-Limit`, `Retry-After` и остальные
- [Troubleshooting](https://foura.ai/docs/troubleshooting/common-issues): частые проблемы и их решения
