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

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

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

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

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

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

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:

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.

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

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

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

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

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.

{
  "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 после исчерпания премиум-трафика. Целевой ресурс не опрашивался, списаний не произошло.

Решение: удалите параметр, вызовите endpoint, входящий в ваш план, или повысьте тариф. Вкладка Limits & Features в Usage & Limits содержит список доступных возможностей. Не повторяйте неизмененный запрос: заголовок Retry-After отсутствует, так как ожидание не изменит результат.

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

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

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

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

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 описан нужный паттерн, а в подразделе Usage & Limits в 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), затем повторите попытку:

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 с небольшим запасом, поэтому его увеличение действительно продлевает время ожидания:

{
  "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, поэтому повторный запрос ничего не стоит. Если это продолжается дольше пары минут, проверьте страницу статуса.

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

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

Чек-лист:

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

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

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

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

Решение: Исправьте указанные поля и отправьте запрос снова. То же самое тело запроса вызовет такую же ошибку 400, поэтому не повторяйте его без изменений. Справочник endpoint reference содержит список всех полей с их типами и ограничениями. В /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. Если целевой ресурс является вашим сервисом, сначала опубликуйте его на публичном хостнейме.

{ "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 (/inspect) это единственный адрес на хосте API, который можно запросить через FourA.

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

Симптом: Вызов /api/proxy/ с exitCountries возвращает HTTP 200 с конвертом ошибки 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.

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

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 для получения актуального каталога, выберите профиль из него и оставляйте unblocker включенным при выборе браузера.

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

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

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

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

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

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

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

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

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

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

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. Полный справочник полей и список поставщиков: Проверки сайтов.

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

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

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

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

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

Обновлено: 13 ноября 2026 г.