Документация › Диагностика › Частые проблемы

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

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

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

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

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

Решение: Переключитесь с single 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 или страницы CAPTCHA

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

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

Решение: Используйте 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 больше попыток.

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

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

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

Решение: Увеличьте timeout_ms (по умолчанию 15с для single, 30с для browser, 45с для 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
  }'

Для браузерных запросов также убедитесь, что ваше значение checkText действительно присутствует на странице. Опечатка всегда приведет к таймауту.

429 Too Many Requests (лимит RPM)

Симптом: API возвращает статус 429 с сообщением "rate limit exceeded".

Причина: Вы превысили лимит запросов в минуту (RPM). Это отличается от лимитов параллельных запросов (см. 503 ниже).

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

import time
import requests

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:
            body = resp.json()
            wait = body.get("retryAfter", 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"}
)

Проверьте текущее использование в Dashboard, чтобы узнать свои rate limits.

503 Service Unavailable

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

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

  1. Достигнут лимит параллелизма. У вас запущено слишком много одновременных запросов. Это отличается от 429, который ограничивает количество запросов в минуту. При 503 вы не превысили свой RPM, но достигли максимума запросов, которые могут выполняться одновременно.
  2. Сервис временно отключен. Проводятся технические работы.

Оба случая включают поле retryAfter в ответе.

Решение: Подождите 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):
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

Если вы регулярно сталкиваетесь с ошибкой 503 (лимит параллельных запросов), уменьшите количество параллельных запросов в вашем пайплайне скрапинга или проверьте лимит вашего тарифа в панели управления.

504 Upstream Timeout

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

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

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

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

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

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

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

Причина: FourA достиг своего движка, но не смог использовать ответ, обычно из-за перезапуска инстанса.

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

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

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

Чек-лист:

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

400 Целевой ресурс указывает на частный/зарезервированный IP

Симптом: API возвращает 400 с Target <ip> resolves to a private/reserved IP до того, как request покидает FourA.

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

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

{ "error": "Target <ip> resolves to a private/reserved IP" }

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 не содержит рабочих выходных узлов, видимая целевому ресурсу страна которых соответствует вашему списку разрешенных. FourA никогда не переключается на незапрошенную страну при установке exitCountries.

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

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")

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

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

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

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

Решение: Для бинарных полезных нагрузок (изображения, protobuf, сырой звук) установите returnBuffer: true в запросе. Тело возвращается как буфер base64 без применения транскодирования символов.

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

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

Неожиданный 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. Полный справочник полей и список вендоров: Anti-Bot Defenses.

Добавьте подстроку validate.data.accept, которая есть только на реальной странице. Без нее страница проверки, возвращенная с HTTP 200, считается успешной, и вы узнаете об ошибке на следующем этапе, а не во время вызова.

Все еще нужна помощь?

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

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

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

Обновлено: 12 августа 2026 г.