# Частые проблемы

> URL: https://foura.ai/ru/docs/troubleshooting/common-issues
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Решения наиболее распространенных проблем при использовании FourA API.

## Пустой или неполный контент

**Симптом:** API возвращает статус 200, но поле `data` пусто или не содержит ожидаемого контента.

**Причина:** целевая страница использует JavaScript для рендеринга контента после начальной загрузки страницы.

**Решение:** переключитесь с одиночного endpoint на browser endpoint. Используйте `checkText`, чтобы убедиться, что контент загрузился:

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'
```

Примечание: browser endpoint возвращает контент в поле `body` (а не `data`).

## 403 Forbidden или страницы верификации

**Симптом:** API возвращает HTML, содержащий страницу верификации или сообщение об отказе в доступе.

**Причина:** целевой сайт распознал запрос как автоматический и заблокировал его.

**Решение:** используйте proxy endpoint для автоматической ротации IP:

```bash
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'
```

Если проблема сохраняется, увеличьте `maxTries`, чтобы дать ротации proxy больше попыток.

Статус 403, возвращенный целевым ресурсом, приходит как HTTP 200 с `status: 403` внутри тела ответа. Ошибка 403 самого вызова с заголовком `X-FourA-Limit` означает другое: см. [403 Not in Your Plan](#403-not-in-your-plan).

## Ошибки таймаута

**Симптом:** запросы завершаются с ошибкой таймаута.

**Причина:** целевая страница загружается дольше настроенного таймаута.

**Решение:** увеличьте `timeout_ms` (по умолчанию 15s для single, 30s для browser, 45s для proxy):

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-site.com",
    "timeout_ms": 60000
  }'
```

Для browser request также убедитесь, что значение `checkText` действительно присутствует на странице. Опечатка приведет к ошибке вызова с `checkText:<your text> not found`.

## 403 Не входит в ваш тариф

**Симптом:** API возвращает 403 с header `X-FourA-Limit` и `reason` со значением `plan_limit_feature` или `plan_limit_premium`.

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

**Причина:** ваш тарифный план не включает вызванный endpoint или переданный параметр. `plan_limit_feature` относится к недоступному endpoint, а также к `exitCountries`, `exitState`, `exitCity`, `exitAsn` или `exitOs` без геотаргетинга. `plan_limit_premium` относится к `exitClass: premium` без премиум-выходов, а также к Proxy-запросу с указанием [exit location](https://foura.ai/docs/api/endpoints#exit-location) после исчерпания премиум-трафика. Целевой ресурс не опрашивался, списаний не произошло.

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

## 429 Слишком много запросов

**Симптом:** API возвращает 429.

**Причина:** запрос отклонен одной из двух проверок, и в ответе указано, какой именно. Если присутствует заголовок `X-FourA-Limit`, достигнут один из лимитов вашего плана: число одновременных запросов или запросов в минуту для данного endpoint, число Browser-запросов за день, либо кредиты или пропускная способность за расчетный период. Если заголовок отсутствует, исчерпан общий минутный лимит платформы для этого сервиса, что связано с общей нагрузкой FourA, а не с вашей.

**Решение:** сначала проверьте `X-FourA-Limit`. Подождите, если до сброса лимита осталось несколько секунд, или остановите запросы, если это не так. Лимиты плана, которые сбрасываются со временем, передают секунды в заголовке `Retry-After` и в `retry_after_seconds`; общий лимит передает их в `retryAfter`:

```python
import time
import requests

# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            limit = resp.headers.get("X-FourA-Limit")
            if limit in STOP_ON:
                raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)
```

Если в заголовке указано `plan_limit_concurrency` или `plan_limit_rate`, решение заключается в ограничении числа одновременно открытых вызовов и числа запусков в минуту, а не в повторных попытках. Повторная отправка отклоненного пакета сразу же приведет к повторному отклонению всего пакета. Отклоненные вызовы не учитываются в лимите в минуту, но если они продолжают поступать со скоростью, превышающей этот лимит более чем в два раза, отклонения переходят в режим ожидания: тело ответа 429 содержит `cooldown: true` и предписывает сделать паузу на 30 секунд (`retry_after_seconds: 30`). В разделе [Run Requests in Parallel](https://foura.ai/docs/how-to/run-requests-in-parallel) описан нужный паттерн, а в подразделе **Usage & Limits** в [Dashboard](https://foura.ai/dashboard) отображаются текущие счетчики рядом с вашими лимитами.

## 503 Сервис недоступен

**Симптом:** API возвращает статус 503.

**Причина:** Это происходит в трех случаях:

1. **Сервис перегружен.** FourA уже выполняет предельно допустимое число одновременных запросов на данном движке для всего суммарного трафика, а не только вашего. Значение `Service at capacity` в поле `error`. Обычно это проходит за несколько секунд.
2. **Сервис временно отключен.** Проводятся технические работы. Значение `Service disabled` в поле `error`.
3. **FourA временно не может проверить ваш ключ.** Значение `API key check temporarily unavailable` в поле `error` с `Retry-After: 5`. С вашим ключом все в порядке.

Во всех трех случаях ответ содержит поле `retryAfter`. Ни один из них не связан с ограничениями тарифа: лимиты вашего тарифа всегда возвращаются с заголовком `X-FourA-Limit` при статусах 403 или 429, но никогда при 503.

**Решение:** Подождите указанное количество секунд (`retryAfter`), затем повторите попытку:

```python
import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")
```

Ошибка 503 при превышении емкости означает, что FourA перегружен, поэтому единственное решение, снизить нагрузку и повторить попытку. Если же вы получаете отказ с кодом 429 и `X-FourA-Limit`, проблема на вашей стороне: уменьшите количество параллельных запросов в вашем пайплайне.

## 504 Время ожидания вышестоящего сервера истекло

**Симптом:** API возвращает 504 с `{"error": "Upstream timeout"}`.

**Причина:** Обработка не завершилась в рамках бюджета времени, заданного для запроса. Причиной могут быть медленный целевой сайт, холодный запуск решения проверки или очень тяжелая страница. Это не связано с вашим ключом, параметрами или proxy.

**Решение:** Выделите запросу больше времени или повторите попытку. FourA ожидает указанный вами `timeout_ms` с небольшим запасом, поэтому его увеличение действительно продлевает время ожидания:

```json
{
  "url": "https://slow-site.com/report",
  "timeout_ms": 90000
}
```

Для `/api/auto/` на защищенном целевом ресурсе первый холодный вызов может занять десятки секунд. Его `timeout_ms` охватывает всю цепочку и принимает значения до 180000.

Когда у самого `/api/auto/` заканчивается этот лимит, вызов все равно возвращает HTTP 200. Тело содержит `error`, начинающийся с `time budget exhausted`, а `status` обычно равен 504 (предыдущая неудавшаяся попытка может оставить там свой собственный статус). Увеличьте `timeout_ms` или повторите попытку.

## 502 Upstream недоступен

**Симптом:** API возвращает 502 с `{"error": "Upstream unavailable"}` или 503 с `{"error": "Backend service unavailable"}`.

**Причина:** FourA не удалось связаться со своим движком (`Upstream unavailable`), либо движок не вернул пригодный ответ (`Backend service unavailable`), обычно из-за перезапуска инстанса. В `/api/browser/` страница ожидает свободный браузер до 10 секунд, если все заняты, и страница, продолжающая ждать после этого, возвращается как эта ошибка 503.

**Решение:** Повторите запрос с небольшой задержкой (backoff). Оба случая классифицируются как `service_error`, а тарифицируется только `success`, поэтому повторный запрос ничего не стоит. Если это продолжается дольше пары минут, проверьте [страницу статуса](https://updates.foura.ai/status).

## 401 Ошибки аутентификации

**Симптом:** Каждый запрос возвращает 401 Unauthorized.

**Чек-лист:**
1. Убедитесь, что заголовок указан как `X-API-Key: YOUR_API_KEY` (а не `Authorization: Bearer` или `Api-Key`)
2. Проверьте API key на наличие лишних пробелов или символов перевода строки
3. Создайте новый ключ в [Dashboard](https://foura.ai/dashboard), если текущий мог быть скомпрометирован

## 400 Некорректный запрос

**Симптом:** Вызов `POST /api/single/`, `/api/proxy/` или `/api/browser/` возвращает 400 с `{"error": "Invalid request: <field>: <reason>; ..."}`.

**Причина:** Поле в теле вашего запроса отсутствует, имеет неверный тип или выходит за допустимые пределы. В сообщении перечисляются неподдерживаемые поля и причины отказа (до пяти полей), после чего следует `and N more`, если есть другие ошибки. Запрос к целевому ресурсу не выполнялся, результат `client_error`, кредиты не списываются.

**Решение:** Исправьте указанные поля и отправьте запрос снова. То же самое тело запроса вызовет такую же ошибку 400, поэтому не повторяйте его без изменений. Справочник [endpoint reference](https://foura.ai/docs/api/endpoints) содержит список всех полей с их типами и ограничениями. В `/api/auto/` та же ошибка возвращается как HTTP 200 с `status: 400` и причиной в `error`.

## 400 Целевой ресурс резолвится в приватный или зарезервированный IP

**Симптом:** API возвращает 400 с `Refusing to fetch <target>: target resolves to a private or reserved IP range` до того, как запрос покидает FourA.

**Причина:** Ваш `url` разрешается в приватный, loopback или зарезервированный диапазон IP (RFC 5735, RFC 6598 или зарезервированные блоки IPv6). FourA отклоняет такие цели, чтобы ее сеть нельзя было использовать для доступа к внутренним хостам.

**Решение:** Запрашивайте публичный URL. При тестировании используйте публичную цель, например `https://example.com` или `https://httpbin.org/get`. Если целевой ресурс является вашим сервисом, сначала опубликуйте его на публичном хостнейме.

```json
{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }
```

Имя хоста, которое не удается разрешить, не отклоняется. Вызов возвращает HTTP 200 с `status: 0` и причиной (`could not resolve <host>: <reason>`), как и любая цель, до которой FourA не может добраться, и он не тарифицируется.

## 400 Пробел в URL

**Симптом:** Single, Proxy или Auto возвращает 400 с `invalid URL: it contains a space; encode it as %20 (the URL as sent: "...")` до того, как запрос покидает FourA.

**Причина:** URL содержит пробел или управляющий символ, обычно это ссылка, взятая со страницы в исходном виде (`javascript: void(0)`, ссылка для шеринга с текстом). Данные не загружаются, результат `client_error`, и кредиты не списываются.

**Решение:** Кодируйте URL перед отправкой (пробел заменяется на `%20`) и пропускайте ссылки, которые не ведут на страницы, например `javascript:`. Браузер загружает такие URL так же, как Chrome.

## 400 Целью является сам API FourA

**Симптом:** API возвращает 400 с `Refusing to fetch <url>: that is the FourA API itself, not a page.` до того, как запрос покидает FourA.

**Причина:** Ваш `url` указывает на `api.foura.ai` или `eu.api.foura.ai`. Краулер обычно делает это, когда разрешает относительную ссылку со страницы относительно URL API вместо собственного URL страницы, поэтому `/category/news/` превращается в `https://eu.api.foura.ai/category/news/`. Ничего не загружается, и кредиты не списываются.

**Решение:** Разрешайте каждую ссылку относительно URL исходной страницы перед отправкой, например с помощью `urljoin(page_url, href)` в Python. [Inspect endpoint](https://foura.ai/docs/api/inspect) (`/inspect`) это единственный адрес на хосте API, который можно запросить через FourA.

## no_eligible_proxy при использовании exitCountries

**Симптом:** Вызов `/api/proxy/` с `exitCountries` возвращает HTTP 200 с конвертом ошибки JSON:

```json
{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}
```

**Причина:** в текущем пуле proxy нет работающей точки выхода, видимая целевому сервису страна которой соответствует вашему разрешенному списку. Стандартный пул никогда не переключается на незапрошенную страну, если задан `exitCountries`. Без `exitCountries` в такой же ситуации возвращается `{"error": "Failed"}`: у FourA не было точки выхода для попытки, поэтому повторите запрос через несколько секунд.

Запрос, в котором указано местоположение точки выхода (`exitState`, `exitCity`, `exitAsn`, `exitOs` или `exitLifetimeMin`, вместе с `exitClass: premium`), отправляется только через premium-выходы. Когда у FourA не остается premium-выходов для выполнения запроса, вызов завершается с `"error": "No premium exit answered for this request"` и тем же `code: no_eligible_proxy`.

**Решение:** сохраните запрошенную область и повторите попытку позже. Пул обновляется примерно каждые десять минут, поэтому страна, для которой сейчас нет совпадений, часто появляется в течение часа.

```python
import time, requests

def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
    for _ in range(max_attempts):
        r = requests.post("https://eu.api.foura.ai/api/proxy/",
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json={"maxTries": 5, "exitCountries": countries,
                  "request": {"method": "GET", "url": url}}).json()
        if r.get("code") == "no_eligible_proxy":
            time.sleep(wait_sec)
            continue
        return r
    raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")
```

Расширяйте список стран только в том случае, если требования вашего рабочего процесса к геолокации действительно изменились. Неявные переключения на другие страны могут нарушить работу зависимой логики дальше по цепочке.

## Профиль браузера отклонен

**Симптом:** вызов возвращает `unknown profile '<id>'`, `no profile matches browser=...` или `browser profile selection requires unblocker:true`.

**Причина:** переданные `profile`, `browser`, `os` или `version` отсутствуют в каталоге, либо передан профиль с `unblocker: false`.

**Решение:** обратитесь к [`GET /api/profiles`](https://foura.ai/docs/api/endpoints#browser-profiles) для получения актуального каталога, выберите профиль из него и оставляйте `unblocker` включенным при выборе браузера.

## Тело ответа возвращается в виде нечитаемого текста

**Симптом:** `data` (или `body`) ответа содержит кракозябры или нечитаемые символы, если целевой ресурс использует кодировку, отличную от UTF-8.

**Причина:** по умолчанию FourA автоматически декодирует тело ответа в UTF-8 на основе заголовка `Content-Type` целевого ресурса или тега HTML `<meta charset>`. Если целевой ресурс указывает неверную кодировку, текст искажается.

**Решение:** для бинарных полезных нагрузок (изображения, protobuf, необработанное аудио) укажите `returnBuffer: true` в запросе. В этом случае Single и Proxy вернут `data` как объект с исходными байтами (`{"type": "Buffer", "data": [<byte values>]}`) без перекодирования набора символов.

```json
{
  "method": "GET",
  "url": "https://example.com/image.png",
  "returnBuffer": true
}
```

Для текстовых ресурсов с неверно указанной кодировкой декодируйте необработанные байты вручную: выполните запрос с `returnBuffer: true`, прочитайте значения байтов в `data.data`, затем декодируйте их с правильной кодировкой.

## Неожиданный HTML вместо JSON

**Симптом:** Ожидался JSON от целевого сайта, но получен HTML.

**Причина:** Целевая страница может отдавать разный контент в зависимости от заголовков.

**Решение:** Добавьте заголовок `Accept` и включите `unblocker` для реалистичных заголовков браузера:

```bash
curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'
```

Вы также можете установить `tryJsonData` в `true`, чтобы FourA автоматически разбирал JSON-ответы.

## Тело ответа содержит страницу проверки, а не контент

**Симптом:** Вызов прошел успешно, `status` равен 200, но `data` (или `body`) содержит проверку на бота вместо нужной страницы.

**Причина:** Целевой ресурс запустил проверку на бота, которую FourA обнаружил, но не смог пройти. В ответе это указано: Single и Proxy возвращают `defense` со значением `solved: false`, а Browser возвращает `defenseSolved: false` с указанием поставщика в `defenses.present`.

**Решение:** Сначала проверьте `defense.vendor`, затем повышайте уровень обработки. Попробуйте другой профиль браузера в Single, перейдите на Proxy для смены выходного узла или используйте Browser для выполнения JavaScript. Полный справочник полей и список поставщиков: [Проверки сайтов](https://foura.ai/docs/api/site-checks).

Добавьте подстроку `validate.data.accept`, которая присутствует только на настоящей странице. Страница проверки, распознанная FourA, никогда не считается успехом: она возвращается с заголовком `X-FourA-Check-Page` и не тарифицируется. Без `validate` нераспознанная FourA страница проверки, возвращенная с кодом HTTP 200, будет считаться успешной, и вы узнаете об этом позже в пайплайне, а не в момент вызова.

## Проблема не решилась?

Если ни одно из решений выше не помогло:

1. Проверьте [страницу статуса](https://updates.foura.ai/status) на наличие текущих инцидентов
2. Проверьте метрики ваших запросов в [Dashboard](https://foura.ai/dashboard)
3. Обратитесь в службу поддержки по адресу support@foura.ai с деталями запроса (укажите `X-FourA-Request-Id` из неудавшегося ответа)

## Следующие шаги

- [Обработка ошибок](https://foura.ai/docs/api/errors): справочник кодов ошибок API
- [Лимиты запросов](https://foura.ai/docs/api/rate-limits): все лимиты тарифных планов и платформы с описанием полей
- [Результаты запросов](https://foura.ai/docs/api/outcomes): как результаты классифицируют произошедшее
- [Проверки сайтов](https://foura.ai/docs/api/site-checks): о чем говорит поле `defense`
- [Выбор подходящего endpoint](https://foura.ai/docs/guides/choosing-task-type): подберите оптимальный подход для вашего целевого ресурса
- [Обзор Dashboard](https://foura.ai/docs/dashboard/overview): мониторинг ваших запросов
